跳到主要内容

官网系统常见问题

1. 官网前台启动报错 "Cannot find module"​

问题：pnpm dev 启动时提示模块找不到。

解决：确保依赖已正确安装。

# 删除 node_modules 重新安装
rm -rf node_modules pnpm-lock.yaml
pnpm install

# 生成 Nuxt 类型声明
pnpm postinstall

2. 前台 API 请求返回 401​

问题：前台页面请求 /app-api/website/xxx 时返回 401。

可能原因：

  • Token 已过期：检查 useCookie('token') 是否存在
  • 未登录访问需要认证的接口（如 /user/*）
  • 后端未启动或代理配置不正确

排查：

# 检查后端是否运行
curl http://localhost:48080/actuator/health

# 检查前台代理配置
# nuxt.config.ts 中 devProxy 是否指向正确的后端地址

3. 微信登录二维码不显示​

问题：登录页二维码无法加载。

排查步骤：

  1. 检查后端微信配置是否正确（application-local.yaml 中的 wx.mp.app-id 和 wx.mp.secret）
  2. 检查前端 redirectUri 参数是否与微信开放平台配置的一致
  3. 检查网络是否能访问 open.weixin.qq.com

4. 后台管理页面显示 "暂无权限"​

问题：登录管理后台后，官网管理菜单不可见或操作按钮灰色。

解决：

  1. 确认使用超级管理员账号登录（role_id = 1）
  2. 检查 system_menu 表中菜单数据是否正确插入
  3. 检查 system_role_menu 表中角色-菜单关联是否配置
  4. 执行菜单 SQL 后需刷新权限缓存或重新登录

5. 源码包上传失败​

问题：管理后台上传源码包时失败。

排查：

  1. 检查 infra 模块的文件存储配置（MinIO / OSS）
  2. 确认文件大小未超过限制
  3. 查看后端日志中 FileApi 的相关错误信息

6. 前台页面数据不更新​

问题：修改了后台配置后，前台页面显示的还是旧数据。

可能原因：

  • 页面缓存：前台 SSR 页面可能被 CDN 或浏览器缓存
  • 数据未及时刷新：站点配置变更后，前台需重新请求

解决：

# 清除 Nuxt 构建缓存
rm -rf .nuxt .output
pnpm dev

7. 数据看板无数据​

问题：管理后台数据看板页面显示为空或零。

可能原因：

  • 数据采集依赖于前台 analytics.client.ts 插件，需有真实用户访问才产生数据
  • 定时任务未运行：检查 AnalyticsDailyAggregateJob 和 AnalyticsFlushJob 是否启用
  • Cookie 同意弹窗未接受：用户未接受 Cookie 则不会上报数据

8. 如何添加新的后台管理页面​

步骤：

  1. 在 views/website/ 下创建页面目录和 index.vue
  2. 在 api/website/ 下创建对应的 API 定义文件
  3. 插入 system_menu 菜单数据（包含组件路径、权限码）
  4. 插入 system_role_menu 分配权限
  5. 重新登录或刷新权限缓存

9. 如何添加新的前台页面​

步骤：

  1. 在 pages/ 下创建 .vue 文件（自动生成路由）
  2. 在 composables/useApi.ts 基础上调用后端接口
  3. 如需认证，在页面中添加 definePageMeta({ middleware: 'auth' })
  4. 更新导航栏和页脚组件

10. 开发调试技巧​

# 后端日志 - 查看 website 模块日志
tail -f logs/yudao.log | grep "website"

# 前端网络请求调试
# 在浏览器中查看 Network 标签页的 /app-api/ 请求

# 数据库查询调试
# 在 application-local.yaml 中启用 mybatis SQL 日志
logging:
  level:
    cn.iocoder.yudao.module.website: debug