> 本文整理自平台文档 docs/wujies/1.x/plugin-dev/backend/local-dev.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-39d0a39e3094-cover.svg)
这一页解决一个问题:改了一行插件代码(或远程应用前端代码),怎么在真实宿主里最快看到它。 三条链路互相独立,先按「你改了什么」对号入座,再只看对应那一节。
| 你改了什么 | 走哪条链路 | 生效方式 |
|---|---|---|
插件后端 Java(cn.wujies.<app>.*) | 链路 1 | 沙箱里即时;真实宿主里要重打 jar,热加载或重启 |
插件前端(wujies/wujies-plugins/frontend/<code>-app) | 链路 2 | 重新构建产物 → 刷新浏览器 |
宿主前端(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/wujies-plugins/ | 插件本体 + 插件前端(pnpm workspace)+ 打包器 + sandbox/ | 根 pom.xml 的 <modules> 里是 wujies-<app> |
plus-ui/ | 宿主前端(Vue 3 / Vite) | 它的 package.json 里 name 写的是 wujies-admin,别被名字骗了 |
# 1) 平台构件先装进本地仓库 —— 插件以已发布构件的形式依赖平台(cn.wujies:*:5.6.2)
cd wujies-platform
& $mvn -B install -DskipTests
# 2) 插件前端的构建期依赖(一次即可)
cd ..\wujies\wujies-plugins
pnpm 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 |
| 默认账号 | 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=dev" -jar "wujies-admin\target\wujies-admin.jar"
脚本在 script/prune/ 下,而它用 $root = Split-Path $PSScriptRoot -Parent 推工程根, 推出来的是 wujies-platform/script,不是仓库根 —— 于是它在 script\wujies-admin\target\... 找不到 jar, 转去打包时又因为那个目录没有 pom.xml 而失败,最后以「打包失败,已中止启动」退出。 同目录的 prune-plugins.ps1 单独跑也有同类问题:不带 -PluginDir 时它去 script\plugins-dist 找, 那里不存在,于是它静默什么都不做(打印「目录不存在,无需清理」)。
powershell -NoProfile -ExecutionPolicy Bypass -File script\prune\prune-plugins.ps1 -PluginDir plugins-dist (先加 -DryRun 看它准备删什么)。
- 启动宿主:用上面的手工命令;
- 清残留 jar:在
wujies-platform下执行
这两条错位记在 wujies-platform/docs/开发问题与解决方案.md 的遗留清单里,状态是「未改」; 脚本一旦修好,这一条就可以删掉。
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 真实宿主:重新打 jar
插件不在平台 reactor 里,构建在插件仓库里做:
cd wujies\wujies-plugins
# 只构建一个插件(-am 会一并构建它依赖的兄弟插件构件,例如 hello 依赖 wujies-member-plugin)
& $mvn -B -pl wujies-hello -am package -DskipTests
产物是 wujies-hello/target/wujies-hello-plugin-1.0.0.jar。
### 2.3 让真实宿主用上新 jar(两种)
| 方式 | 怎么做 | 生效时机 |
|---|---|---|
| 走市场(推荐) | .\package.ps1 -Plugin wujies-hello -SigningKey keys\private.pem → 上传版本 → 控制台「部署」或「我的应用」里升级 | 热加载,不重启(响应里 hotLoaded: true) |
| 本地偷懒 | 把新 jar 覆盖 wujies-platform/plugins-dist/ 下的同名文件,然后重启宿主 | 启动时加载 |
判断依据是 plugins-dist/active-plugins.txt(每行 appCode=jar 文件名):
只加载清单里登记的那个;不在清单、也不
- 运行期(启动加载与热加载都走
PluginRuntimeManager)以它为准:同一个appCode名下有多个 jar 时,
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-39d0a39e3094-guide.svg)


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