常见问题

本文汇总商业版前端接入、联调、权限和项目定制配置中的高频问题，可作为开发和排查过程中的快速索引。

启动后接口全部报错

优先检查：

• 后端是否已经启动
• VITE_API_PROXY_URL 是否写对
• 浏览器请求路径是否与 src/api 定义一致，例如登录 /api/v1/auth/signin、菜单 /api/v3/system/menus

Java 默认代理为 http://localhost:13001，Nest.js 默认为 http://localhost:13000。只保留一个未注释的代理目标，修改后重启前端，见 快速开始。

Java 版请求没有签名头，是不是异常

不一定。Java 当前公开安全配置返回 signatureRequired: false，共享前端会自动跳过签名，仍使用 Bearer Token 与后端权限校验。是否需要签名以 /api/v1/crypto/security-config 为准，不要在前端强行开启。

Java 版没有代码生成器或 MinIO 标签

Java 不包含开发工具模块和 AI 代码生成器。MinIO 的后端存储链路可用，但前端尚缺 MINIO 类型、展示标签和筛选选项，启用时需要补齐。完整差异见 功能边界。

登录后菜单空白

优先检查：

• 后端用户信息和菜单接口是否返回成功
• 当前账号是否绑定角色
• 菜单组件路径是否和前端页面实际路径一致

页面刷新后回到登录页

优先检查：

• Refresh Token Cookie 是否写入成功
• 是否需要开启 withCredentials
• 反向代理是否影响 Cookie

按钮权限不生效

优先检查：

• 页面 meta.authList 是否声明
• 后端菜单里是否创建了按钮权限项
• 当前角色是否分配了该权限

切换品牌文案后页面没变化

优先检查：

• 是改了前端静态默认值，还是改了后端站点配置
• 公开站点配置接口是否返回了新值
• 浏览器缓存是否仍在使用旧资源

想继续看更底层的通用文档

可以结合这些开源文档一起看：

• 项目结构
• 路由和菜单
• 主题配置
• 国际化

检查清单

如果 FAQ 中的问题已全部排除，建议再确认：

• 登录、刷新、菜单、按钮权限和站点配置链路均正常。
• 新增页面和接口已完成前后端同步配置。
• 生产环境与本地环境的 API 地址、Cookie、CORS 和部署路径差异已记录。