> 本文整理自平台文档 docs/wujies/5.x/platform/plugin/advanced/contributing.mdx,用于站点内容演示。
(https://console.wujies.cn/remote-apps/cms-assets/doc-8b8091c4da91-cover.svg)
这一页解决的是改平台代码时最容易反复踩的几件事:
| 你遇到的问题 | 这一页给什么 |
|---|---|
| 命令抄了跑不通(路径是旧名) | 一份逐条核对过的命令清单 |
| 测试"全绿"其实一条没跑 | profile 标签纪律 |
| 改了后端但行为没变 | "改完必须重建 jar"的原因与做法 |
| 前端远程应用构建全绿、浏览器里炸 | tools:check 一条命令覆盖哪几类问题 |
| 提交前不知道要自检什么 | 一份清单 |
只要写应用、不改平台代码,看 [插件开发](/docs/wujies/5.x/platform/plugin/) 与 [跟着 hello 读源码](/docs/wujies/5.x/platform/plugin/demo) 就够了 —— 本页针对的是平台侧改动 (wujies-admin / wujies-common-* / wujies-modules/* / 插件加载与市场逻辑)。
三个仓库
没有共同 git 根,各自分支、各自提交、各自推送。改一个功能经常要两边都提交。
| 仓库 | 目录 | 内容 | 当前分支 |
|---|---|---|---|
| 后端 | wujies-platform/ | Java / Spring Boot + 平台 SQL 脚本 | feature/app-market |
| 宿主前端 | wujies-admin/ | Vue 3 / Vite,应用市场与远程应用运行时(远程产物落 app-market-dist/remote-apps/) | feature/app-market |
| 应用仓库 | wujies/plugins/wujies-<code>-plugin/(12 个) | 一个应用一个仓库:后端 src/ + app.json + migrations/ + frontend/ + 打包脚本 + keys/ | master |
1. wujies-admin 在不同位置指不同东西:wujies-platform/wujies-admin/ 是后端启动模块 (有 pom.xml、产物 wujies-admin.jar);工作区顶层那个 wujies-admin/ 是宿主前端 (src/、vite.config.ts、scripts/,远程产物落它的 app-market-dist/remote-apps/)。 2. 宿主前端仓库的 package.json 里 name 也写的是 wujies-admin(版本 5.5.1-2.5.1)—— 判据:有 vite.config.ts / src/ 的就是顶层那个前端仓库, 凡是指向 src/plugins/、src/views/ 的路径都在这里。它早期的目录名 plus-ui 已不再使用。
分支名以实际仓库配置为准(上表是核对过的当前值),别照抄旧文档里的 my-main / my-ts —— 那两个名字在仓库里已经不存在。每个仓库的推送远程都叫 wujies (git@gitee.com:wujies/<repo>.git);后端与宿主前端仓库里残留的 origin 指向上游模板,不要往它推。
环境与常用命令
本机没有把 JDK / Maven 加进 PATH,所以先设两个变量。下面的命令都在 wujies-platform/ 下执行(它是 Maven 根)。
$env:JAVA_HOME = "C:\Users\<you>\.jdks\corretto-23.0.2" # 目标字节码是 JDK 17
$mvn = "C:\Program Files\JetBrains\IntelliJ IDEA 2025.3.3\plugins\maven\lib\maven3\bin\mvn.cmd"
# 全反应堆编译
& $mvn -B -q compile -DskipTests
# 跑应用市场模块的测试(根 pom 默认 skipTests=true,必须显式打开并指定 profile)
& $mvn -pl wujies-modules/wujies-app-market -B test "-DskipTests=false" "-Dprofiles.active=dev"
# 打可运行 jar(只有以 fat jar 部署时才需要;本机 IDEA 跑宿主读的是 target/classes,见下)
& $mvn -pl wujies-admin -am -B install -DskipTests
# 启动宿主(手工命令;-D 参数的引号不能省 —— PowerShell 会把 -Dloader.path=x 拆成 /path=x)
java "-Dloader.path=plugins-dist" "-Dspring.profiles.active=dev" -jar "wujies-admin\target\wujies-admin.jar"
本机日常的跑法是在 IDEA 里启动宿主(读 wujies-admin/target/classes,端口 8086), 改完插件后端不要重启:
# 新写/新改的控制器必须显式重载才进路由(宿主 application.yml 已开 dev-mode)
# 权限 app:dev:reload,body 形如 {"appCode":"hello"}
curl -X POST http://localhost:8086/app/dev/reload -H "Content-Type: application/json" -d '{\"appCode\":\"hello\"}'
宿主前端 wujies-admin/ 起 npm run dev(端口取 .env.development 的 VITE_APP_PORT, 接口走 /dev-api 代理到后端 8086)。远程产物优先读各应用仓库自己的 frontend/dist/, 其次才是 wujies-admin/app-market-dist/remote-apps/。 两个落位目录都可以用环境变量指到绝对路径(app-market.deploy.plugin-dir / frontend-dir, 默认相对进程工作目录):
$env:WUJIES_PLUGIN_DIR = "<...>\wujies-platform\plugins-dist"
$env:WUJIES_FRONTEND_DIR = "<...>\wujies-admin\app-market-dist\remote-apps"
启动日志会打两行 [deploy] plugin-dir / frontend-dir = <绝对路径>,目录不存在还会 WARN —— 换启动目录后先看这两行。
插件侧(在该应用仓库根 wujies\plugins\wujies-hello-plugin\ 下执行;独立仓库只有一个 POM,不用 -pl,也不传 -Plugin):
# 只构建这个应用的 jar
& $mvn -B package -DskipTests
# 打完整应用包(自动构建前后端 + 可选签名),这是发布路径
.\package.ps1 -SigningKey keys\private.pem
.\package.ps1 -Keygen # 只生成密钥对,落到 keys\
以 fat jar 部署的那台机器上,改了后端代码后只跑 mvn compile(哪怕成功)不会重建那个 fat jar, 于是你测的是旧代码,很容易得出「功能没生效」的错误结论,然后去改本来是对的实现。 下结论前先确认 jar 是新的。 本机在 IDEA 里跑宿主时读的是 target/classes, mvn compile 就够,但绝不要在 JVM 还活着的时候跑 mvn install(见下一条)。
⚠️ 两种直觉做法都会骗你:在 fat jar 顶层找 cn/wujies/...class 找不到 (模块类是嵌套在 BOOT-INF/lib/wujies-<模块>.jar 里的,得到的是假阴性); 看嵌套条目的 LastWriteTime 也见过与内部 class 时间不一致。 可靠做法是把嵌套 jar 抽出来看里面那个 class。
maven-compiler-plugin 的增量检查会先清空输出目录再全编, 正在运行、按需懒解析类的 JVM 会抛 NoClassDefFoundError。真实发生过。
测试纪律
根 pom 的 surefire 用 <groups>${profiles.active}</groups> 过滤测试。 没打 @Tag("dev") / @Tag("local") / @Tag("prod") 的测试根本不会被执行。
症状很好认:Tests run 总数没变,但 BUILD SUCCESS —— 看着全绿,其实你的测试没跑。
照抄 wujies-modules/wujies-app-market 下现有
本文导览
(https://console.wujies.cn/remote-apps/cms-assets/doc-8b8091c4da91-guide.svg)


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