> 本文整理自平台文档 docs/wujies/5.x/platform/plugin/basics/manifest.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-f2a32a8526f9-cover.svg)
app.json 是应用在平台上的唯一权威描述:编码、版本、产物路径、菜单树、依赖。 上架、安装、升级、卸载全部读它。写错了不会在编译期报错,只会在安装时失败或 在运行期静默失效(菜单点不开、按钮不出现、C 端 404)。
这一页解决三件事:
1. 每个字段真实的类型、必填性与取值约束(对着 AppManifest.java 与校验器写,不凭印象); 2. menus[] 怎么设计,尤其是 type: "F" 按钮 —— 漏了会留下永久性的坏数据; 3. key 的命名转换,以及"为什么不能只用 perms 推 key"。
parseAndValidate(manifestJson, expectedAppCode);菜单部分复用安装时的 AppMenuPlanner.plan(...), 所以"保存时通过、安装时失败"不可能发生。 这几个类都是 2026-10-30 抽出来的上架判据内核(wujies-modules/wujies-market-core), 平台安装侧与中心上架服务共用同一份。
- Java 映射:
wujies-platform/wujies-modules/wujies-market-core/src/main/java/cn/wujies/appmarket/domain/AppManifest.java - 校验入口:
wujies-market-core/.../appmarket/service/AppManifestValidator.java的
最小可用清单
范例应用是 wujies-hello,它的清单有 13 个顶层字段(没有 migrations / config):
{
"code": "hello",
"name": "Hello 示例",
"version": "1.0.2",
"type": "plugin",
"engine": ">=5.6.2 <6.0.0",
"author": { "name": "无界创镜" },
"license": "MIT",
"summary": "插件开发范例:一个表 + 五组演示(调用宿主系统服务、跨插件调用、从插件开放 /open 接口、两种定时任务、标准 CRUD 列表页),前端页面随包一起发。",
"dependencies": [
{ "code": "member" }
],
"categories": ["开发工具"],
"tags": ["示例", "插件开发", "PoC"],
"assets": {
"backend": "backend/wujies-hello-plugin-1.0.2.jar",
"frontend": "frontend/index.js"
},
"menus": [
{
"key": "hello",
"name": "Hello 示例",
"type": "M",
"path": "hello",
"icon": "ri:emotion-happy-line",
"order": 99,
"children": [
{
"key": "hello-probe",
"name": "运行时探针",
"type": "C",
"path": "probe",
"component": "remote:hello/demo/home",
"perms": "hello:probe:view",
"icon": "ri:pulse-line",
"order": 0,
"children": [
{ "key": "hello-probe-view", "name": "查看探针", "type": "F", "path": "",
"perms": "hello:probe:view", "icon": "#", "order": 1 }
]
}
]
}
]
}
源文件是 plugins/wujies-hello-plugin/app.json(下称"仓库路径", 按 [设计文档索引](/docs/wujies/5.x/platform/architecture/design-docs) 的约定,仓库路径不是站内链接,故用行内代码写)。 新插件直接照它复制,不要从别的业务插件里抄(那些带一堆历史包袱)。
顶层字段
| 字段 | Java 类型 | 必填 | 含义与约束 |
|---|---|---|---|
code | string | 是 | 应用编码。正则 ^[a-z][a-z0-9-]{1,62}$(2–63 位,中心上架服务 AppAdminController.APP_CODE_PATTERN 在建应用时钉住它;平台侧 AppManifestValidator 只查非空 + 与所属应用一致)。同时是表名前缀、权限前缀、远程视图前缀 |
name | string | 是 | 应用名称。DB 列 app_info.app_name 为 varchar(64) |
version | string | 是 | 语义化版本,正则 ^\d+\.\d+\.\d+(-[0-9A-Za-z.]+)?$ |
type | string | 否 | module 内置模块 / app 应用 / plugin 插件,默认 module。第三方包写 app 或 plugin,怎么选见下方「type:三种形态怎么选」 |
engine | string | 否 | 平台版本约束,见下 |
author | object | 否 | 只有 name、url 两个子字段 |
license | string | 否 | 如 MIT / Apache-2.0。DB 列 varchar(32) |
licenseRequired | boolean | 否 | 这个包要不要本机授权凭证解锁才能装与加载,默认 false(社区件)。判据写在包内清单里、且在包签名覆盖范围之内 —— 把它从 true 改成 false 会当场验签失败。付费件写 true,此时中心上架要求目录条目为 private(LicenseVisibilityRule)。三档口径见[授权与版本](/docs/wujies/5.x/license/) |
summary | string | 否 | 一句话简介,市场卡片用。DB 列 varchar(200) |
categories | string[] | 否 | 分类名,必须与 app_category 里已存在的分类对得上 |
tags | string[] | 否 | 搜索标签。DB 里存成逗号分隔的 varchar(200) |
menus | MenuDef[] | 否 | 菜单树,安装时幂等写入 sys_menu |
dependencies | Dependency[] | 否 | 依赖的其它应用。没装/没启用时安装与升级会被拦住并明确告诉你缺谁,见 [dependencies[]](#dependencies) |
migrations | Migration[] | 否 | 预留字段,当前不参与执行(见下) |
config | object | 否 | 预留字段,当前没有任何代码读它(见下) |
assets | object | 否 | 前后端产物路径 |
宿主 Jackson 配了 fail_on_unknown_properties: false (wujies-admin/src/main/resources/application.yml)。所以拼错的键名不会让解析失败, 只会表现为"这个功能没生效",且日志里什么都没有。
排查手段只有一条:对着 AppManifest.java 的字段名逐字比。改动字段名时, AppManifest.java 与已上架的历史包两处都要看(早期那份 app.schema.json 草案已不存在)。
### type:三种形态怎么选
判据参考 NiuCloud —— 它把扩展分成应用和插件两类,界线是业务体量,不是代码放在哪:
| 形态 | 什么时候用 | 谁执行安装 |
|---|---|---|
module | 平台自带、代码随宿主一起发布的内置模块,不加载任何外部产物 | ModuleAppInstaller:注册菜单 + 授权 + 迁移 |
app | 一套完整业务体系:有自己的前后台与数据闭环,能围绕它组织业务。现有 5 个属于这类:商城、会员、即时通讯、考试、企业数据 | PluginAppInstaller |
plugin | 功能单一、依附在应用之上的增量能力,与其它单元几乎无耦合。现有 7 个属于这类:支付、财务、报价、图床、社 |
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-f2a32a8526f9-guide.svg)


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