本地联调

这一页解决一个问题：改了一行插件代码（或远程应用前端代码），怎么在真实宿主里最快看到它。 三条链路互相独立，先按「你改了什么」对号入座，再只看对应那一节。

契约与 Mapper XML 都在插件工程自己的 src/ 下（平台里没有 *-api 契约模块）， 所以三条链路都不需要碰平台代码 —— 只有改了宿主自己的代码时才要重建 wujies-admin.jar。

一、前置（一次性）复制标题链接

三个仓库，没有共同 git 根，各自提交：

# 1) 平台构件先装进本地仓库 —— 插件以已发布构件的形式依赖平台（cn.wujies:*:5.6.2）
cd wujies-platform
& $mvn -B install -DskipTests

# 2) 插件前端的构建期依赖（一次即可）
cd ..\wujies\wujies-plugins
pnpm install

plugin-dir: plugins-dist
frontend-dir: ../wujies-admin/app-market-dist/remote-apps

新起一个宿主实例（手工命令，-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"

二、链路 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：

插件的 migrations/*.sql 会在沙箱里按文件名顺序自动执行（MySQL 方言会被改写成 H2 能跑的语句）。 -ApiPath 是给已废弃的 *-api 契约模块准备的，当前用不到；插件自己的类都在插件 jar 里。

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（两种）复制标题链接

判断依据是 plugins-dist/active-plugins.txt（每行 appCode=jar 文件名）：

• 运行期（启动加载与热加载都走 PluginRuntimeManager）以它为准：同一个 appCode 名下有多个 jar 时， 只加载清单里登记的那个；不在清单、也不属于任何已登记应用的 jar 被当作「手工放置」， 按文件名推导 appCode 加载（该 appCode 已有生效版本时不覆盖）。
• 启动期那条 loader.path（PluginClassPathLoader，Spring 之前执行）现在也只挂清单里的 jar， 其余会打印「跳过 N 个不在 active-plugins.txt 里的 jar（刻意不挂载）」；清单文件缺失/为空时退回「全挂」。

所以：覆盖同名文件最省事，清单不用改；换文件名就必须同步改 active-plugins.txt， 否则容易出现「看着有 jar、其实没生效」。

⚠️ 手工放进去的 jar 只解决「后端产物在不在」：它没有安装记录，也不会建菜单 （菜单只在安装/升级时按 app.json 幂等 upsert）。菜单要出现，还是得走一次安装或升级。

# 重启前清掉同一 appCode 的旧版本 jar（按 active-plugins.txt，只删不在用的那些）
cd wujies-platform
powershell -NoProfile -ExecutionPolicy Bypass -File script\prune\prune-plugins.ps1 -PluginDir plugins-dist

2.4 范例应用 wujies-hello 的接口阶梯复制标题链接

后端装载问题按这个顺序打，能一步分开「装载」还是「数据」：

/hello/greet 与 /hello/item/list 通、/open/** 通、跨插件那两条按「装没装会员」给不同结果 —— 这七条的真实源码与逐行解释见 跟着 hello 读源码。

三、链路 2：插件前端（远程 ESM）复制标题链接

远程应用是独立构建的 ESM 产物，跑在宿主同源上下文里。两个环境变量决定它能不能被 dev server 提供：

cd wujies\wujies-plugins

# 宿主仓库根（含 package.json、src/、src/utils、src/enums 的那一层）
$env:WUJIES_UI_DIR = 'C:\Users\TX\Desktop\ruoyi\plus-ui'

# 产物落点：宿主的 app-market-dist\remote-apps（工厂会自动追加 <appCode> 子目录）
$env:WUJIES_FRONTEND_DIST = 'C:\Users\TX\Desktop\ruoyi\plus-ui\app-market-dist\remote-apps'

pnpm --filter ./frontend/hello-app run build

发布前跑一遍守门脚本（都在 plus-ui 下）：

cd plus-ui
npm run check:remote      # 组件能不能解析 + 产物里有没有 process.env 残留
npm run check:globals     # 宿主自动导入宇宙里的名字有没有变成裸全局
npm run check:runtime     # 运行时垫片的导出面覆盖不覆盖产物里的 bare import

3.1 让宿主知道「去哪拿这份 ESM」复制标题链接

正常路径是运行期问服务端：登录后 GET /app/runtime/remote-apps 返回本租户已启用应用的入口， 形如 {"appCode":"hello","entry":"/remote-apps/hello/index.js?v=1.0.0"}（带 ?v= 是为了升级后不吃旧缓存）。 纯后端应用（清单没写 assets.frontend）不会出现在里面，这是正常的。

临时指向别的产物时，用静态清单（优先级更高）：

VITE_APP_MARKET_REMOTE_APPS = hello=/remote-apps/hello/index.js

格式是 code=url,code2=url2；只写 url 时只能预加载、不能按需装载。写进 plus-ui/.env.development 后要重启 dev server（环境变量在启动时读取）。开发环境另有内置的 demo-app / gallery 两条静态声明 （其中 demo-app 已从应用目录去掉，那条已失效）。 解析器与优先级见 plus-ui/src/plugins/appmarket/bootstrap.ts。

四、链路 3：宿主前端壳复制标题链接

cd plus-ui
npm run dev      # 80 端口；predev 会先跑 gen:runtime 生成运行时垫片

改了 plus-ui/src/**（宿主自己的页面、应用市场运行时、菜单与权限）走常规热更新即可。

五、怎么确认插件真的加载了复制标题链接

后端侧（从上到下，越往下越接近「业务真的通了」）：

前端侧：

六、常见现象对照复制标题链接

更多按症状查的入口：故障排查；任务步骤与日志的读法：应用任务中心。

相关阅读复制标题链接

• 本地开发与联调方案 —— 本页的补充：对标 Halo / NiuCloud 的机制，给出「远程宿主 + 本地代码」四条路径与一条命令的自动化脚本
• 后端工程 —— 插件模块结构、provided 依赖、Mapper 与 XML 的位置
• 前端远程应用 —— 构建配置工厂、组件白名单、运行时垫片
• 跟着 hello 读源码 —— 四个演示点的真实源码
• 应用清单 app.json · 数据库迁移 · 种子数据与站点配置
• 必须遵守的不变量 —— 类可见 vs bean 可见、两套加载机制、拦截器链
• 15 分钟跑起来 —— 从零把平台和后端跑起来