中国 帮助

本地联调

这一页解决一个问题:改了一行插件代码(或远程应用前端代码),怎么在真实宿主里最快看到它。 三条链路互相独立,先按「你改了什么」对号入座,再只看对应那一节。 你改了什么 走哪条链路 生效方式 插件后端 Java(cn

本地联调
封面

> 本文整理自平台文档 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/**、应用市场运行时)链路 3Vite 热更新

契约与 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 server80(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:

章节导览
THE END

喜欢就支持以下吧

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

回到内容