> 本文整理自平台文档 docs/wujies/5.x/platform/plugin/manual-run.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-fdc82fbe5e98-cover.svg)
这一页是不用后台页面的那条路:全程命令行为,把「clone 一个已发布的应用仓库 → 本地改后端 + 改前端 → 跑起来 → 打包 → 上架」 每一步的确切命令写清楚。看得懂这页,就能不打开开发台也把开发做完。
它对照的是 [Halo 的两种插件开发方式](https://docs.halo.run/developer-guide/plugin/basics/devtools):
| Halo | Wujies | 特点 |
|---|---|---|
./gradlew haloServer(DevTools,推荐) | [可视化开发台](/docs/wujies/5.x/platform/plugin/console) 的「启动后端」+「启动前端」 | 编译、加载、监听都由宿主代劳 |
runtime-mode: development + --halo.plugin.fixed-plugin-path | 本页:写 fixed-plugin-path + POST /app/dev/reload | 自己敲命令,但要几个接口都能用 |
两条路用的是同一套开发模式接口,区别只在于「谁按下按钮」。命令行的好处是不依赖页面、能写进脚本、 CI 里也能跑;代价是每次改完要自己触发编译和热加载。
一个应用(插件)跑不起来属于自己的进程:后端代码装载进宿主的 JVM,在宿主的子 Spring 上下文里; 前端是宿主浏览器里 import() 的 ESM 产物,共享宿主那份 Vue / Element Plus 实例。 所以本地开发的对象永远是「一个跑着的宿主 + 一份被它加载的插件产物」,Halo 同理。
想完全不碰真实宿主,可以用沙箱(H2 内存库,不连 MySQL / Redis)挂起单个插件 jar。⚠️ sandbox 模块只在早期那棵单体仓库 wujies-plugins 里,那棵仓库已下线、不再作为开发入口,下面仅当本机还留着历史检出时才可用:
# 先在应用仓库打出 jar
cd <插件仓库>
mvn -B package -DskipTests
# 再在单体仓库的历史检出里起沙箱
cd ..\wujies\wujies-plugins
mvn -B -pl sandbox spring-boot:run `
"-Dspring-boot.run.arguments=--sandbox.plugin-jar=<插件仓库绝对路径>\target\<artifactId>-<版本>.jar"
沙箱只验后端接口,菜单和前端页面看不到 —— 那部分必须走真实宿主。
先决条件
| 需要 | 说明 |
|---|---|
| JDK 17+ | 宿主与插件同一个 java.version;JAVA_HOME 要指到它 |
| Maven | 命令行有 mvn,或用 IDE 自带的 mvn.cmd |
| Node 18+ 与 npm | 只有要构建前端时才需要 |
| 一个跑起来的宿主 | 默认 http://127.0.0.1:8086,context-path 为 / |
| 一个能用的令牌 | 后面所有 curl 都要带 Authorization: Bearer <token> 与 clientid: <VITE_APP_CLIENT_ID> 两个头 |
本机的 ~/.m2 里有平台构件 | 见下面「第一次在本机编译插件」 |
取令牌最省事的办法:浏览器登录管理端,从任意请求的 Request Headers 里把 Authorization 与 clientid 抄出来。 下面统一写成 $TOKEN / $CLIENT。
### 第一次在本机编译插件
独立插件仓库的 pom.xml 里父构件是 cn.wujies.plugins:wujies-plugins-parent:1.0.0,<relativePath/> 留空 ⇒ Maven 直接去仓库找它,不再依赖「它在单体仓库里的相对位置」。父 POM、wujies-common-*、兄弟插件构件目前只发布到本机的 ~/.m2(还没进 Maven 中央仓库),所以陌生机器 clone 下来会卡在「找不到 wujies-plugins-parent」。本机准备一次即可:
# 1) 平台构件:在宿主仓库安装 admin 及其依赖模块
# ⚠️ 必须先停掉正在跑的宿主 JVM,否则会出现 NoClassDefFoundError
cd <...>\wujies-platform
mvn -pl wujies-admin -am -B install -DskipTests
# 2) 插件父 POM:只装根 POM 本身,不构建子模块
# ⚠️ 母本 POM 在已下线的单体仓库 wujies-plugins(Gitee 取不到),仅本机有历史检出时才装得了
cd <...>\wujies\wujies-plugins
mvn -B -N install
这两步做过之后,独立插件仓库在本机就能 mvn compile / package 通过。构件发布进度见 [插件 SDK 与依赖包](/docs/wujies/5.x/platform/plugin/sdk)。
第 1 步:开启开发模式(一次性)
宿主 application.yml:
app-market:
plugin-runtime:
# 开发模式总开关:false 时下面这些接口全部 404
dev-mode: true
# 留空 = 默认扫描项目根的 plugins/,把其中每个插件工程都加载(Halo 的 fixed-plugin-path)
# 要加载别处的工程时,在这里写绝对路径(可多行)
fixed-plugin-path: []
# 可选:显式指定 mvn 可执行文件;留空由宿主自行定位
maven-command: ""
改完重启宿主。启动时宿主会加载 fixed-plugin-path 里列出的每个工程;留空则加载项目根 plugins/ 里的全部插件工程(前提是已有 target/classes 或 target/*.jar; 没有只告警,不会替你跑 Maven)。配置项可以写插件工程、插件容器(如 plugins/), 也可以写含多个 wujies-* 的单体仓库根 —— 单体仓库根只用于定位,不会批量加载。
空配置时宿主按约定位置找插件容器(相对宿主进程工作目录):
../plugins
plugins
../../plugins
wujies/plugins
容器判定:目录下至少有一个 wujies-*/app.json。单体仓库的命中条件是目录里同时存在 package.ps1 与 wujies-hello/。
独立插件仓库本身就是插件工程(仓库根有 app.json):放到 plugins/wujies-<code>-plugin/ 就进了默认扫描范围;放在别处则写进 fixed-plugin-path。
定位优先级恒为:fixed-plugin-path > 约定自动探测,同名应用只认前面那一份。
第 2 步:取源码
已发布的应用都在 Gitee 组织 wujies 下,一个应用一个仓库,仓库名 wujies-<编码>-plugin (与 Maven artifactId 一致);后端在仓库根,前端在 frontend/。
git clone git@gitee.com:wujies/wujies-enterprise-plugin.git
wujies-enterprise-plugin/
├── app.json 清单:编码、版本、产物、菜单与权限(唯一权威描述)
├── pom.xml 后端 Maven 工程,parent = wujies-plugins-parent
├── src/main/java/ Controller / Service / Mapper / domain
├── migrations/ 建表与种子数据,按文件名顺序执行
└── frontend/ 前端远程应用(vite.config.ts + src/index.ts + src/views)
早期 11 个应用全挤在一棵单体仓库 wujies-plugins 里;那棵仓库已下线(Gitee 取不到), 不再是取源码的入口 —— 只有本机还留着它的历史检出时,才用于打开发包、起沙箱这些母本操作。 后面每一步都按「一个应用一个仓库」写。
第 3 步:确认宿主找到了这份代码
fixed-plugin-path 里写对了,宿主启动时就已经加载并定位好;这一步只是核对:
curl -H "Authorization: Bearer $TOKEN" -H "clientid: $CLIENT" `
http://127.0.0.1:8086/app/dev/overview
看 fixedPluginPath(配置值)、searchRoots(本次实际扫描的根)、 plugins(扫出来的应用列表,每项带 code / layout / `artifactP
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-fdc82fbe5e98-guide.svg)


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