常见问题排查
排查时应先确认问题属于中间件配置、菜单发布、角色授权、前端运行态、后端接口校验还是依赖版本。未定位原因前，不得通过隐藏错误、空数据或临时绕权兜底。
菜单没有出现
- 确认菜单清单已上传。
- 确认菜单版本已发布。
- 确认当前角色已授权。
- 确认 PCWEB 使用
system_menu，APP / 小程序使用app_menu。 - 确认前端登录后已 rebuild runtime 或重新拉取菜单。
默认页为空
- 确认中间件已配置默认页。
- 确认默认页对应菜单已发布。
- 确认当前角色有默认页权限。
- PCWEB 确认使用
runtime.defaultRoute，不得直接拼接接口原始字段。
页面 404
- PCWEB 确认
registerPage已注册对应pageCode。 - 确认
routePath与本地路由适配一致。 - 确认组件路径存在且构建能解析。
- APP / 小程序确认页面路径已在项目页面配置中注册。
按钮不显示
- 确认菜单中存在对应
actionCode。 - 确认当前角色已授权该动作。
- 确认前端使用同一个
actionCode调用canAction或按钮权限组件。 - 确认不是只授权了页面
.view。
按钮显示但接口无权限
- 确认
actionCode下配置了grantApis。 - 确认
grantApis.resource与后端接口路径一致。 - 确认
grantApis.action与 HTTP 方法一致。 - 确认角色授权后 Casbin 已生效。
- 确认后端
CheckPermission使用同一组Resource / Action。
PCWEB 有权限但 APP 无权限
- PCWEB 使用
system_menu，APP / 小程序使用app_menu，两者不是同一份运行态菜单。 - 确认
app_menu已上传、发布并授权。 - 确认 APP / 小程序 runtime provider 获取的是应用菜单权限。
APP 有菜单但接口无权限
- 菜单展示只证明页面或动作可见。
- 确认动作下的
grantApis已配置。 - 确认角色授权后的
grantApis已进入 Casbin。 - 确认后端写接口执行了
CheckPermission。
grantApis 配了但 Casbin 没生效
- 确认菜单版本已发布。
- 确认角色授权已保存。
- 确认授权的是当前登录上下文中的角色。
- 重新登录或重建运行态后再验证。
- 用有权限和无权限角色分别验证接口结果。
pageCode / actionCode 前后不一致
- 以菜单 JSON 为准统一前端和后端口径。
- PCWEB
registerPage使用菜单中的pageCode。 - 前端按钮判断使用菜单中的
actionCode。 - 后端接口权限使用菜单
grantApis的resource/action。
前端误用了 SystemKey / PermanentKey
- 立即从前端配置、源码、构建产物和提交记录中移除。
- 改由后端通过
clsdk-go保存并使用服务态密钥。 - 前端只保留
app-id、addons-type、x-token等用户态上下文。 - 如果密钥已经外泄，按内部安全流程轮换密钥。
正式项目误用了本地 replace / file:
- 后端删除
go.mod中正式不允许提交的本地replace。 - PCWEB 和 APP / 小程序删除
package.json中正式不允许提交的本地file:依赖。 - 改为 Gitee tag 依赖。
- 重新安装依赖并运行项目构建。