打包应用

这一页只讲打包这一段：在插件仓库根用 wujies/wujies-plugins/package.ps1 把一个应用打成一个可上传的 zip，以及它顺手产出的另外两样东西（暂存目录、.package-info.json）。

打包器只有这一个，对所有应用通用：它的事实来源是插件的 app.json（脚本里 $appCode = $manifest.code、$appVersion = $manifest.version、$backendRel = $manifest.assets.backend），没有一处写死应用名。想改「打什么、叫什么」改清单；想改「这一次怎么打」用参数。

签名算法、上传与发布、部署落位各有一页：密钥与签名、上架与发布、应用生命周期。这一页只保证「命令能照着敲、产物能照着核对」。

最短路径复制标题链接

# 工作目录 = 插件仓库根
cd wujies\wujies-plugins

powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 -Plugin wujies-gallery

产物是默认输出目录 <插件仓库的上一级>\.plugin-dist\<code>\<version>\ 下的三个东西。注意这个目录在插件仓库之外（本机是 C:\Users\TX\Desktop\ruoyi\wujies\.plugin-dist\gallery\1.0.5\）：

-Plugin 实际上必须传：不传时脚本会自动选用插件仓库根下唯一含 app.json 的子目录（Resolve-PluginDir），而当前有 11 个（wujies-enterprise / exam / finance / gallery / hello / im / mall / member / pay / quote / social），自动选用这条路走不到，脚本会报错并列出候选。

开发包（-Dev）复制标题链接

日常联调、或者只想把包展开看看结构时，用开发包：

# 工作目录 = 插件仓库根
.\package.ps1 -Plugin wujies-demo -Dev

产物落在 .plugin-dist\<code>\dev\（而不是 <code>\<version>\）：

.plugin-dist\demo\dev\
├── demo-1.0.0.zip
├── demo-1.0.0.package-info.json
└── demo-1.0.0\               ← 暂存目录，zip 的内容就是它

三条必须知道的约束：

1. -Dev 与 -SigningKey 互斥。 传了 -Dev 又传私钥会直接报错；要签名就去掉 -Dev。
2. enforce 模式下不能上传。 宿主当前 app-market.security.mode=enforce，未签名包会在 POST /app/package/parse 阶段被拒。开发包不是"绕过签名"，只是"不签名"。
3. 它仍然会完整执行构建与组装。 前端构建、后端 Maven、迁移脚本拷贝、打包一样不少， 只是少了签名这一步。

发布一个版本（release.ps1）复制标题链接

上面那条命令只回答「把一个包打出来」。要回答「发布一个版本」—— 打完包还能在 git 上留下一个可回溯、可下载的版本点 —— 用同一个目录下的 release.ps1：

# 工作目录 = 插件仓库根
cd wujies\wujies-plugins

.\release.ps1 -Plugin wujies-hello              # 打包 → 打 tag → 推 tag
.\release.ps1 -Plugin wujies-hello -DryRun      # 干跑：跑完所有守卫 + 打印计划，什么都不做
.\release.ps1 -Plugin wujies-hello -NoPush      # 只在本机打 tag，确认后再自己推

两个脚本不是替换关系：

版本号只有一个来源：源 app.json 的 version复制标题链接

⚠️ release.ps1 刻意没有 -Version 参数。

原因是一个真实踩过的坑：-Version 只改写包内那份 app.json、不动源文件（见下文「参数交互」第 2 条）。长期这么用就会出现「源 app.json 写 1.0.1，而实际已经发到 1.0.4」的漂移 —— 包可以重打，tag 一旦打错就指向了与内容不符的版本，事后没法补救。

所以发布流程唯一认源 app.json 的 version，要发新版本先改清单再提交：

# 1) 改 <插件>/app.json 的 version（包内 jar 名要跟着改，脚本会拦下不自洽的）
# 2) 提交（守卫要求工作区干净，所以这一步必须在发布之前做完）
# 3) 发布
.\release.ps1 -Plugin wujies-hello

tag 约定：<appCode>-v<version>复制标题链接

例：hello-v1.0.2、mall-v1.0.5、enterprise-v1.0.2（appCode 就是清单的 code）。

• 一个仓库里有多个应用，tag 必须能区分应用 —— 前缀用 appCode，它本来就是全平台的应用身份（app_version.app_code、前端目录名、包名前缀都用它）；
• 中间那个 -v 是分隔符，不是装饰：应用目录名自带 -（wujies-hello），没有它就没法把「应用名」与「版本号」一刀切开，列版本、比大小、机器解析都要靠猜。

于是「按应用列出所有版本」是一条确定的命令：

git tag -l 'hello-v*'                          # hello 的全部已发布版本
git tag -l --sort=version:refname 'hello-v*'   # 按版本号排序
git show hello-v1.0.2                          # 这一版发的到底是什么

用附注 tag（git tag -a）而不是轻量 tag：说明里写了应用名 / 版本 / 包文件名 / 大小 / sha256 / md5 / 是否签名 / 分支 / 提交 / 构建时间，git show <tag> 就能核对整包有没有被换过。

前置守卫（每条都拦，失败就明确退出，绝不半途发布）复制标题链接

没有 remote 怎么办复制标题链接

不算失败（拆仓库初期很常见）。tag 照样建在本地，脚本打印：

未配置 remote ⇒ tag 已建在本地；配置 remote 后执行：
    git -C "<插件仓库>" remote add origin <仓库地址>
    git -C "<插件仓库>" push origin hello-v1.0.2

有 remote 时默认推 origin；只有一个 remote 就用它；有多个又没有 origin 会报错并列出候选，用 -Remote <名字> 指定。

release（带 zip 附件的下载页）怎么发复制标题链接

⚠️ 脚本刻意没有用 API 自动创建 release。 Gitee 与 GitHub 的 release API 形状差得多，本机又没有 token 可验，写出来就是没验证过的代码。脚本改为把确定的部分说死：

手工创建 release（可选，给"供下载"用）
  要传的文件  : <...>\.plugin-dist\hello\1.0.2\hello-1.0.2.zip
  入口        : https://gitee.com/impressivel/wujies-plugins/releases/new
  选 tag      : hello-v1.0.2

入口地址从 remote URL 推出来（gitee.com / github.com 两种都认），剩下「点发布」那一下交给人。想用 API 自动化就自己接，token 一律走环境变量占位符（GITEE_TOKEN / GITHUB_TOKEN），不要写进脚本或文档。

发布完还要做的最后一件事：传到市场复制标题链接

打包与 tag 都不动宿主磁盘，市场里也不会自动出现新版本。release.ps1 会把这几步打在最后：

①要传的就是 release.ps1 打出来的那个 zip，一个字节都别改：宿主 mode=enforce 会在这一步验签（未签名 / 验签失败直接拒）。上传接口会把解析出的 packageSha256 回给你，与脚本打印的 sha256 对一下就能确认没传错文件。详见上架与发布。

别用 -SkipBuild 发布：它会跳过构建、只重新组装现有产物，tag 说明里的 sha256 反映的是旧产物。

命令与参数复制标题链接

# ① 指定插件（推荐）
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 -Plugin wujies-gallery

# ② 不传 -Plugin —— 插件仓库根下只有一个含 app.json 的插件时才可用
powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1

# ③ 脚本被复制进插件目录时的写法
powershell -NoProfile -ExecutionPolicy Bypass -File wujies-gallery\package.ps1

脚本实际跑的四个步骤复制标题链接

1/4 构建前端远程产物
    工作目录 = <插件仓库>/frontend
    命令     = pnpm --filter <前端工程 package.json 的 name> run build
               （读不到 name 时用默认 filter @wujies-plugins/<code>-app）
    注入     = WUJIES_UI_DIR（宿主前端仓库，别名 @/utils 等指向它）
               WUJIES_FRONTEND_DIST（产物落点，即 -FrontendDist 的父目录）

2/4 构建后端插件 jar
    工作目录 = <插件仓库>（不是插件目录）
    命令     = mvn -B -pl <插件目录名> -am package -DskipTests

3/4 组装包目录（暂存目录 <OutDir>/<code>-<version>/）

    （签名插在这一步之后、第 4 步之前）

4/4 Compress-Archive 打 zip，算 MD5 / SHA256，写 <code>-<version>.package-info.json

两个刻意的做法，改脚本时别当成笔误：

• 前端走 pnpm --filter，不直接 node .../vite.js：wujies-plugins/pnpm-workspace.yaml 把 frontend/*-app 注册成工作区包，vite 被提升到仓库根的 node_modules，写死相对路径会失效。前端工程的 package.json 里 name 形如 @wujies-plugins/gallery-app。
• 后端走 mvn -pl <模块名> -am，不用 mvn -f <插件>/pom.xml：插件之间会互相依赖（mall 依赖 member / pay / im，全是 provided），单模块构建时这些兄弟构件只能去远程仓库找，本地没装就直接失败。-am 让 Maven 在反应堆内把上游一起建掉。

打包前脚本还会做几项自检，-SkipBuild / -SkipFrontend 时不该拦人的检查会跳过：

产物落在哪、长什么样复制标题链接

三样产物的落点复制标题链接

输出目录的决定顺序（参数永远最优先）：

⚠️ 第 2 与第 3 条语义不同：WUJIES_OUT_DIR 就是最终目录；WUJIES_PLUGIN_DIST 是根、还要补两层。

包内结构（以已打出的 gallery-1.0.5 为例）复制标题链接

gallery-1.0.5/
├── app.json                                     清单
├── signature.txt                                分离式签名（-SigningKey / 自动发现私钥时才有）
├── backend/wujies-gallery-plugin-1.0.5.jar      文件名必须等于清单的 assets.backend
├── frontend/index.js                            远程 ESM 入口（`*.map` 已被剔除）
│   └── assets/...
└── migrations/                                  只收顶层 `*.sql`，没有就不建这个目录
    ├── 01-create-gallery-tables.sql
    ├── 02-create-gallery-website-config.sql
    └── 03-create-gallery-seed-data.sql

包根只允许 app.json、signature.txt 与 backend/、frontend/、migrations/ 三个目录，多一个文件就会被安全检查拒掉 —— 白名单与拒绝清单见安全校验模式。

元信息文件复制标题链接

<输出目录>\<code>-<version>.package-info.json 的字段与用途（下面是已打出的一份真实内容）：

{
  "appCode": "gallery",
  "appName": "图床管理",
  "version": "1.0.5",
  "fileName": "gallery-1.0.5.zip",
  "packageSize": 206011,
  "packageMd5": "93e2f4d08074b8a5e882384240e823d0",
  "packageSha256": "0263a55a63e48150fbfe2e3d90cc874228b6c7822a55a943f6da2b2ae9290993",
  "builtAt": "2026-10-01 09:50:59"
}

走上传接口（POST /app/package/parse）时这几个摘要由后端算好返回，不用手填；只有走控制台表单手工登记版本时才需要对照这个文件。接口细节见上架与发布。

想自己再核一遍 zip 结构：

Add-Type -AssemblyName System.IO.Compression.FileSystem
$z = [System.IO.Compression.ZipFile]::OpenRead("..\.plugin-dist\gallery\1.0.5\gallery-1.0.5.zip")
$z.Entries | Select-Object FullName, Length
$z.Dispose()

后端 jar 的名字怎么来的复制标题链接

这里有两个版本号，最容易搞混：

也就是说：Maven 打出来的 jar 名与应用版本无关，包内名字由打包器改成「应用版本」——这样 assets.backend 的声明才自洽。平台根 pom 的 <revision>（5.6.2）只用于 cn.wujies:* 依赖坐标（wujies-plugins/pom.xml 的 <platform.version>），不参与这两个文件名。

配套两条：

• 清单里的 assets.backend 必须与包内那份一致。-Version 时脚本会同步改写包内清单的 version 与 assets.backend，并打印「包内清单已改写: version=…, assets.backend=…」。
• 没传 -Version 但两者不一致时只 Write-Warning（不是错误）：assets.backend 声明的文件名是 X，但按插件 artifactId 与应用版本推导应为 Y。这类错几乎总是「改了 version 忘了改 assets.backend」，会在很远的地方（部署时报「找不到后端产物」）才炸出来，所以在打包时就说清。

参数交互（会踩的几种组合）复制标题链接

1. 签名：-SigningKey / 自动发现 / 自动 keygen / -NoSign复制标题链接

宿主当前是 app-market.security.mode=enforce（见 wujies-platform/wujies-admin/src/main/resources/application.yml），不签名的包在上传时就会被拒。所以脚本的默认行为是：

powershell -NoProfile -ExecutionPolicy Bypass -File package.ps1 -Keygen -SigningKey keys\private.pem

2. -Version 只改包内清单复制标题链接

-Version 1.0.5 改写的是包内那份 app.json（并同步改写 assets.backend、把包内 jar 改名），源 app.json 保持不动 —— 打完包仓库是干净的。要让它成为长期版本，自己改清单的 version。

两个约束：

• 格式校验是 ^[0-9]+(\.[0-9]+){0,3}([-+][0-9A-Za-z.-]+)?$，不合法直接报错；
• 后端清单校验比打包脚本严（要求 x.y.z），见上架与发布。打包能过不等于上传能过。

覆盖版本号时脚本用 .NET 写文件而不是 Set-Content，因为必须不带 BOM（后端用 Jackson 解析包内清单，开头的 BOM 会让它直接报错；PowerShell 5.1 的 Set-Content -Encoding UTF8 会写 BOM）。不覆盖版本号时是原样 Copy-Item，保留作者写的格式与顺序。

3. -SkipBuild / -SkipFrontend / 纯前端应用复制标题链接

清单里 assets.backend 与 assets.frontend 两样都没有才会报「包里没有任何产物」。

4. 打包器要能定位平台仓库和宿主前端仓库复制标题链接

脚本不靠「往上数几层」推路径，而是按候选探测（两个仓库可能不在同一棵目录树里）：

迁移脚本的打包规则复制标题链接

迁移脚本的命名约定与四种文件形态（建表 / 种子数据 / 字典 / 站点配置）见数据库迁移与种子数据与站点配置。

常见错误对照表复制标题链接

相关阅读复制标题链接

• 打包与上架 —— 整条发布链路与「上传 / 发布 / 部署」的区别
• 密钥与签名 —— 签名算法、换钥三步、旧包就地重签
• 上架与发布 —— 端点、版本状态流转、上传时的那次校验
• 安全校验模式 —— 产物白名单与 off / warn / enforce
• 应用清单 app.json —— code / version / assets / menus 字段
• 数据库迁移 —— 迁移脚本的四条硬规矩
• 应用生命周期 —— 包上传之后被平台怎么接住
• 跟着 hello 读源码 —— 最小的可打包应用长什么样