常见问题

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

启动后接口全部报错

优先检查：

• 后端是否已经启动
• VITE_API_PROXY_URL 是否写对
• 浏览器请求是否真的走到了 /api/v1

登录后菜单空白

优先检查：

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

页面刷新后回到登录页

优先检查：

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

按钮权限不生效

优先检查：

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

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

优先检查：

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

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

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

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

检查清单

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

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