> 本文整理自平台文档 docs/wujies/1.x/plugin-dev/advanced/menus.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-1f1d4cd0bc59-cover.svg)
这一页解决什么问题:你在 app.json 里声明了一棵菜单树,安装后它会变成 sys_menu 里的行。 本页讲清四件事 —— 平台怎么写这些行(三条规则)、按钮为什么必须写进清单、 menu_key 的命名有哪些硬约束,以及这些行装完之后谁保护它们。
字段逐个的解释(key / name / type / path / component / perms / order / children 的类型与上限) 在 [应用清单 app.json](/docs/wujies/1.x/plugin-dev/basics/manifest) 的 menus[] 一节,本页不重复。 归属机制的设计推导在 [菜单归属与保护](/docs/wujies/1.x/advanced/menu-ownership)。
一个真实的最小例子
wujies/wujies-plugins/wujies-hello/app.json 是范例应用(推荐照着它抄):
"menus": [
{
"key": "hello",
"name": "Hello 示例",
"type": "M",
"path": "hello",
"children": [
{
"key": "hello-plugin-dev",
"name": "插件开发范例",
"type": "C",
"path": "plugin-dev",
"component": "remote:hello/demo/plugin-dev",
"perms": "hello:plugindev:view",
"children": [
{ "key": "hello-plugindev-view", "name": "查看范例页", "type": "F",
"path": "", "perms": "hello:plugindev:view", "icon": "#", "order": 1 }
]
}
]
}
]
一条铁律:不要手写 INSERT INTO sys_menu
菜单只能通过清单声明,安装 / 升级时由平台的 AppMenuPlanner 算出计划、幂等落库。 理由:菜单以 menu_key 为身份,同名 key 复用既有 menu_id。 手写 SQL 会绕开这个机制 —— 升级时插出一套重复菜单,或者让租户已经分配好的权限全部失效。
### 三条核心规则
| # | 规则 | 不这么做会怎样 |
|---|---|---|
| 1 | 按 key 幂等 —— 重复装同一版本不产生重复菜单 | 每次同步多一套菜单,每套的 menu_id 都不同 |
| 2 | 跨版本复用 menu_id —— 新版本里同名 key 沿用旧 menu_id | 租户已有的 sys_role_menu 授权指向旧 ID,升级后全部失效 |
| 3 | 深度优先、父先于子 —— 落库时父菜单 ID 必定已确定 | 子菜单的 parent_id 落成空或指向未创建的行 |
规则 2 的直接推论:已经发布过的 key 不要改。改 key 等于新菜单, 旧菜单会被判为 obsolete(作废)—— 平台只标记不动它, 调用方应当把它停用而不是删除(可能还有租户停留在旧版本)。
### 校验器还会拒绝什么
AppMenuPlanner 是纯逻辑类,清单不合法时在上传阶段就报错。以下都是它的真实文案:
| 报错 | 触发条件 |
|---|---|
第 N 个菜单 key 非法(需为小写字母开头的 2-63 位小写字母/数字/连字符): x | key 不匹配 ^[a-z][a-z0-9-]{1,62}$ |
菜单 key 重复: x | 同一份清单里 key 撞了 |
菜单 x 缺少 name / 菜单 x 缺少 type | 必填项缺 |
菜单 x 的 type 非法(只能是 M/C/F): y | type 写了别的值 |
菜单 x 是页面菜单(C),必须声明 component | C 类型没写 component |
按钮 x 必须声明 perms | F 类型没写 perms |
菜单树深度超过上限 5,请检查清单嵌套 | 嵌套超过 5 层 |
完整报错清单见 [应用清单 app.json](/docs/wujies/1.x/plugin-dev/basics/manifest) 的「校验报错文案速查」。
按钮(type: "F")必须写进清单
type: "F" 不是可选项。漏了会同时踩三个坑:
| 漏写的后果 | 表现 |
|---|---|
| 全新部署装上应用 | 没有按钮 —— 前端 v-hasPermi 过不了,租户用户看不到任何操作按钮 |
| 菜单管理页 | 按钮不受保护,管理员能随手删掉 |
| 「彻底删除」应用 | 按钮删不掉(归属映射里没有它),留成"父菜单没了的孤儿" |
第三条的根因:归属映射 app_version_menu 里只有清单声明过的菜单, 而平台侧的归属查询(AppMenuOwnershipProvider)要顺着 parent_id 把后代一起算成该应用的 (AppMenuTreeExpander)。清单里没有的那些按钮只能靠这个兜底被"连坐"认领; 一旦连坐关系也断了,管理员在菜单管理页就能随手删掉应用按钮,恢复只能靠重装。
把新 key 映射到既有的按钮 ID,否则下一次升级会建出一套重复按钮。
图床(gallery)的 23 个按钮就是这么补进 wujies/wujies-plugins/wujies-gallery/app.json 的,配套脚本是 wujies-platform/script/sql/update/fix_gallery_menu_tree.sql。它值得当模板看,因为一段做三件事:
| 节 | 做什么 | 关键点 |
|---|---|---|
| 1 | 用原 menu_id 插回被误删的菜单行 | 值取自 app.json(清单是唯一事实来源);父行按原 ID 回来,按钮的 parent_id 自动重新挂上 |
| 2 | 把新 key 登记进 app_version_menu(key → 既有 menu_id) | 下次升级按 key 复用这些既有按钮,而不是新建一套 |
| 3 | 把这批菜单授权给租户管理员角色 | 与安装时的授权行为一致(见下节) |
整个脚本用 INSERT ... WHERE NOT EXISTS / NOT EXISTS 写成幂等,可重复执行。
menu_key 的命名硬约束与转换
key 只能是小写字母开头的 2–63 位小写字母 / 数字 / 连字符(^[a-z][a-z0-9-]{1,62}$)。 但 perms 里普遍有驼峰 —— 直接拿 perms 当 key 会在上传时被拒:
第 N 个菜单 key 非法(需为小写字母开头的 2-63 位小写字母/数字/连字符): member-member-adjustPoints
正确做法:kebab = 驼峰前插 '-' 再整体小写(member:balanceLog:query → member-balance-log-query)。
两者没有关系,别一起转。真实清单里 key 全小写连字符,path 保留驼峰: {"key": "gallery-image-category", "path": "imageCategory"}、 {"key": "gallery-image-access-log", "path": "imageAccessLog"}(见 gallery 的 app.json)。 path 是前端路由地址,与 [权限标识](/docs/wujies/1.x/plugin-dev/frontend/) 无关。
菜单多的模块要"生成"而不是手写
会员 68 行、商城更多。手写必然出错,而且有三个必须避开的陷阱。
### 陷阱一:app.json 与 seed SQL 必须同源
两份手写必然漂移,而漂移的后果是升级时建出一套重复菜单。 必须由同一份数据生成这两样东西:先从库里读整棵菜单树 → 一次生成 app.json 与 menu_key → menu_id 映射 → 再由映射生成 seed SQL。
### 陷阱二:F 行的 key 要父键限定
同一个 perms 可能在多行菜单上重复出现(工作台一套按钮、各管理页又各一套)。 生成 F 行 key 时不能只用 perms:
- 用父键限定(
im-workbench-<perms 尾>与im-conversation-<perms 尾>); - 再加
-<menu_id>兜底; - 最后断言同版本内 key 唯一(不唯一的话上传就会被
菜单 key 重复拒掉)。
生成前先自查:


评论区需要浏览器启用 JavaScript 才能加载。