> 本文整理自平台文档 docs/wujies/5.x/platform/plugin/backend/local-dev.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-6030e90cddc4-cover.svg)
这一页解决一个问题:改了一行插件代码(或远程应用前端代码),怎么在真实宿主里最快看到它。 三条链路互相独立,先按「你改了什么」对号入座,再只看对应那一节。
| 你改了什么 | 走哪条链路 | 生效方式 |
|---|---|---|
插件后端 Java(cn.wujies.<app>.*) | 链路 1 | 沙箱里即时;真实宿主开了 dev-mode 时点「启动后端」(自动编译 + 加载 + 监听),不重启 |
插件前端(wujies-<code>-plugin/frontend) | 链路 2 | 启动前端 watch 构建 → 刷新浏览器 |
宿主前端(plus-ui/src/**、应用市场运行时) | 链路 3 | Vite 热更新 |
契约与 Mapper XML 都在插件工程自己的 src/ 下(平台里没有 *-api 契约模块), 所以三条链路都不需要碰平台代码 —— 只有改了宿主自己的代码时才要重建 wujies-admin.jar。
---
一、前置(一次性)
三个仓库,没有共同 git 根,各自提交:
| 目录 | 是什么 | 判据 |
|---|---|---|
wujies-platform/ | 后端(Java / Spring Boot)+ SQL | 有 pom.xml、wujies-admin/target/wujies-admin.jar |
wujies/plugins/wujies-<code>-plugin/(12 个) | 一个应用一个仓库:后端 + 前端工程 + 打包脚本 | 仓库根有 app.json、pom.xml、frontend/、package.ps1 |
plus-ui/ | 宿主前端(Vue 3 / Vite) | 它的 package.json 里 name 写的是 wujies-admin,别被名字骗了 |
# 1) 平台构件先装进本地仓库 —— 插件以已发布构件的形式依赖平台(cn.wujies:*:5.6.2)
cd wujies-platform
& $mvn -B install -DskipTests
# 2) 该应用前端的构建期依赖(每个仓库装一次,依赖来自 npm 上的 @wujies/*)
cd ..\wujies\plugins\wujies-hello-plugin\frontend
npm install
| 项 | 值 |
|---|---|
| 后端端口 | 8086(wujies-admin/src/main/resources/application.yml 的 server.port) |
| 前端 dev server | 80(plus-ui/.env.development 的 VITE_APP_PORT),/dev-api 代理到 http://127.0.0.1:8086 |
| 沙箱端口 | 18080(历史单体仓的沙箱,见 2.1,已不作为入口) |
| 默认账号 | admin / admin123,租户 000000 |
app-market.deploy 下两个路径都是相对路径,见 wujies-admin/src/main/resources/application.yml:
plugin-dir: plugins-dist
frontend-dir: ../wujies-admin/app-market-dist/remote-apps
在别的目录启动,插件 jar 与远程应用前端产物会落到错误的位置 —— 表现是「装成功了但功能打不开」。
新起一个宿主实例(手工命令,-D 参数的引号不能省 —— PowerShell 会把 -Dloader.path=x 拆成 /path=x):
cd wujies-platform
java "-Dloader.path=plugins-dist" "-Dspring.profiles.active=prod" -jar "wujies-admin\target\wujies-admin.jar"
早期工程根下有 script/prune/start-host.ps1 与 script/prune/prune-plugins.ps1 两个脚本; 2026-11-01 起,它们已从仓库删除(script/prune/ 目录本身也没了)。当时它们把工程根算错的 现象不再存在 —— 现在没有脚本可跑。
(按 active-plugins.txt 只删不在用的那些),清单本身由部署链路维护。
- 启动宿主:用上面的手工命令;
- 清残留 jar:在
wujies-platform下手工删除plugins-dist/里同一appCode的旧版本文件
如果日后重新提供等价脚本,这一条可以改回推荐执行。
app-market.plugin-runtime.enabled 默认 true(每插件独立类加载器)。要退回旧的兼容机制, 必须用 JVM 参数,因为启动器在 Spring 之前执行、读不到 yml: "-Dapp-market.plugin-runtime.enabled=false"。只在 yml 里改的表现是「插件完全不加载」。
---
二、链路 1:插件后端(Java)
### 2.1 最快回路:沙箱(H2,不连 MySQL / Redis / RabbitMQ)
⚠️ 沙箱属于历史单体仓 wujies-plugins,该仓已下线、不再作为开发入口;本节仅作机制说明,只有本机还留着历史检出时才可用。
sandbox 模块是一个独立的 Spring Boot 应用,它把一个插件 jar 挂起来跑, 用来在还没有完整平台环境时看自己的接口。
cd wujies\wujies-plugins
powershell -NoProfile -ExecutionPolicy Bypass -File sandbox\run.ps1 -Plugin wujies-hello
脚本会先 mvn -pl wujies-hello,sandbox package -DskipTests(-SkipBuild 可跳过), 再用扁平 classpath 启动,端口 18080:
| 地址 | 作用 |
|---|---|
http://localhost:18080/sandbox | 自检:插件装上没有、挂了几条路由 |
http://localhost:18080/sandbox/beans | 插件上下文全部 bean —— 排查「注入不进来」最有用 |
http://localhost:18080/h2-console | 直接查沙箱内存库(用户 sa,空密码) |
插件的 migrations/*.sql 会在沙箱里按文件名顺序自动执行(MySQL 方言会被改写成 H2 能跑的语句)。 -ApiPath 是给已废弃的 *-api 契约模块准备的,当前用不到;插件自己的类都在插件 jar 里。
它不做安装、签名、菜单同步、迁移记账;它的 H2 schema 是开发用最小集; 它刻意复现「宿主看不到插件」这个边界(沙箱里不能用注入拿插件服务)。 能力与已知限制见 wujies-plugins/sandbox/README.md;边界场景(鉴权链、租户、跨插件、SnailJob) 必须回到真实宿主验。
### 2.2 真实宿主:一键启动后端(开发模式)
宿主开了 dev-mode 时,最快的方式是在 开发工具 → 插件开发 的列表行上点「更多 → 启动后端」。 它等价于 Halo 插件模板的 ./gradlew haloServer,但在已运行的宿主里完成:
1. 源码比 target/classes 新(或没有产物)时,自动执行 mvn -B -f <仓库根>/pom.xml compile -DskipTests; 2. 加载 target/classes(已加载则先卸载上一代,换新类加载器); 3. 开启 target/ 监听,之后每次编译产物稳定约 2 秒后自动热加载。
弹窗会显示编译输出、耗时、产物路径、接口 / 组件 / Mapper / 转换器数量与监听状态。 Maven 由宿主进程自动定位:app-market.plugin-runtime.maven-command → MAVEN_HOME / M2_HOME → PATH → IDEA 内置 → 常见安装目录 → Maven Wrapper 缓存。 宿主关掉后监听失效,重启后重新点一次即可(会自动加载,不用先手动热加载)。
不想用页面时,手动回路仍然有效:
cd wujies\plugins\wujies-hello-plugin
& $mvn -B compile -DskipTests
# 然后在开发台点「热加载」「仅开启监听」,或调 POST /app/dev/reload
产物是 target/classes/,热加载直接消费这个目录,宿主不重启。 需要打开发包或正式上架时才 package:


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