> 本文整理自平台文档 docs/wujies/5.x/platform/plugin/quickstart.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-1753691482e9-cover.svg)
这一页带你从零做出第一个插件:新建骨架 → 构建产物 → 本地安装 → 验证接口 → 开发调试 → 打包发布。
示例插件叫 demo,它自带一张 demo_item 表和一个标准 CRUD 页面。全程不需要改平台代码。
0. 准备环境(一次性)
| 工具 | 版本 | 用途 |
|---|---|---|
| JDK | 17+ | 构建插件、签名 |
| Maven | 3.9+ | 编译后端 |
| Node.js | 18+(仓库要求 20+) | 生成骨架、构建前端 |
| pnpm | 10.x | 前端依赖安装,corepack enable pnpm 即可(也可直接用 npm) |
| 插件目录 | 项目根 plugins/ | 每个插件一个独立仓库,默认扫描这里 |
然后在宿主 application.yml 打开开发模式,重启一次宿主:
app-market:
plugin-runtime:
dev-mode: true
# 留空 = 默认扫描项目根的 plugins/,启动时加载其中的全部插件
fixed-plugin-path: []
# 插件放别处时再写绝对路径(可多行)
# fixed-plugin-path:
# - C:/Users/you/code/wujies-demo-plugin
重启后登录后台,能看到 「开发工具 → 插件开发」 就说明准备好了。 开关关闭时,整个开发端点不注册,页面会显示「开发模式未就绪」。
开发模式会从本地路径直接加载 target/classes 或 jar,绕过包白名单、校验和与签名校验。 能调用它的人等于能在宿主 JVM 里执行任意代码。绝不要在生产环境打开。
1. 新建插件
在项目根执行一条命令,默认输出到 plugins/wujies-<code>-plugin/:
node tools/create-plugin/create-plugin.mjs --code demo --name "演示应用"
同一个生成器支持三种变体,产物结构一致:
| 变体 | 命令 | 内容 |
|---|---|---|
| 全栈(默认) | --code demo --name "演示应用" | 后端 CRUD + 前端列表页 |
| 仅后端 | 追加 --backend-only(或 --no-frontend) | 表 + 五个接口,不生成前端工程 |
| 仅前端 | 追加 --frontend-only(或 --no-backend) | 一个静态页面 + 菜单,不生成 pom / 迁移 |
| 参数 | 示例 | 说明 |
|---|---|---|
--code | demo | 小写字母开头,2–32 位字母/数字;同时决定包名、表前缀、权限前缀 |
--name | 演示应用 | 后台菜单显示名,最多 40 字 |
--version | 1.0.0 | 语义化版本,默认 1.0.0 |
--description | 我的第一个插件 | 可选,写进 app.json 的 summary |
--out | D:\dev\plugins | 可选,换输出目录(默认项目根 plugins/) |
--template | path\to\hello | 可选,换模板工程(默认 plugins/wujies-hello-plugin) |
生成器不会改动任何仓库根 pom.xml:每个插件都是独立仓库、独立 POM。
### 生成了什么
plugins/wujies-demo-plugin/
├── app.json 菜单、权限、产物路径、版本
├── pom.xml 独立 POM(父 POM 由 Maven 仓库提供)
├── migrations/
│ └── 01-create-demo-item.sql 建表 + 2 条种子数据(幂等)
├── src/main/java/cn/wujies/demo/
│ ├── DemoPluginApplication.java ★ 启动类(Halo 式:装载完调 start(),卸载前调 stop())
│ ├── controller/DemoItemController.java
│ ├── domain/DemoItem.java
│ ├── domain/bo/DemoItemBo.java
│ ├── domain/vo/DemoItemVo.java
│ ├── mapper/DemoItemMapper.java
│ └── service/IDemoItemService.java + impl/DemoItemServiceImpl.java
├── frontend/
│ ├── package.json
│ ├── vite.config.ts
│ └── src/
│ ├── index.ts 入口契约,视图键 item
│ └── views/ItemList.vue 标准 CRUD 页面
├── package.ps1 / package.cmd 完整打包脚本(与单体仓库同一份母本;密钥自己 -Keygen 生成)
└── README.md
--frontend-only 不生成 pom.xml 与 migrations/,前端视图键是 home。
菜单也已写好:父菜单「演示应用」→ 子菜单「数据」→ 四个按钮权限 (demo:item:query/add/edit/remove),页面组件是 remote:demo/item。
2. 启动开发回路
开发台列表每行都有一个 一键开发 按钮(没装过时显示「安装并开发」):首次先安装(迁移 + 菜单)→ 按需编译后端 → 热加载 → 开启监听 → 启动前端 watch,一次做完;之后改完代码编译(前端保存即可),宿主全程不重启。 行末「更多」里仍保留细粒度按钮(启动后端 / 启动前端 / 热加载 / 仅开启监听), 想单步执行或排查时用它们。
### 2.1 启动后端(自动编译 + 加载 + 监听)
在 开发工具 → 插件开发 里找到 demo,点 一键开发(等价于只点后端轨道上的 启动后端)。服务端会:
1. 比较 src/main 与 target/classes 的时间戳;源码更新或还没有产物时自动执行 mvn -f plugins/wujies-demo-plugin/pom.xml compile -DskipTests,否则跳过 Maven; 2. 用独立类加载器加载最新 target/classes(应用已在运行时先卸载上一代); 3. 开启 target/ 监听:之后每次编译,产物稳定约 2 秒后自动热加载。
弹窗会列出本次是否编译、编译耗时、加载到的接口 / 组件 / Mapper 数量与监听状态。 等价于 Halo 插件模板的 ./gradlew haloServer,区别是这里跑在你已经启动的宿主里,不额外起进程。
终端等价命令(不想点按钮时):
cd plugins\wujies-demo-plugin
# 编译后端 → target/classes/
mvn -B compile -DskipTests
# 再让开发台加载(或直接点「热加载」「仅开启监听」)
- 宿主进程里找不到
mvn时,页面会提示可配置 - 只改前端、不碰 Java 时,不需要重新点「启动后端」。
- 监听是进程内状态:重启宿主后需要重新点一次「启动后端」(会自动加载,不用先手动热加载)。
### 2.2 启动前端(watch 构建)
点前端轨道上的 启动前端。宿主会在该插件的 frontend/ 目录常驻执行:
cd plugins\wujies-demo-plugin\frontend
npm install # 首次
npm run dev # = vite build --watch
保存 frontend/src/ 后 Vite 增量重建 frontend/dist/,宿主 dev server 本来就直接从这个目录提供 /remote-apps/demo/,刷新应用页面即可看到效果。 页面上的「日志」可以查看 watch 进程输出,「停止前端」会连同子进程一起结束。
- 这里没有 HMR:远程应用依赖宿主的 Vue / Element Plus 共享实例,独立 dev server 会引入第二套实例,
- 不想常驻进程时,用「构建一次」或
npm run build。 - 宿主关闭时会一并停掉它拉
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-1753691482e9-guide.svg)


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