多端项目结构与 CI 自动发布
本篇要点:把一个要同时发微信、H5、App、鸿蒙四个端的项目,整理成多人能同时改、发布不依赖某台机器的结构,并把能自动化的部分交给流水线。 前置文章:《进阶:适配鸿蒙 NEXT 与上架》把第四个端跑通了;这一章处理端变多之后必然出现的问题——工程本身开始互相踩。
1 为什么需要它:一个 manifest.json 上解三次冲突
先说现状,三句话能说完:
三个小组共用一个 manifest.json 和一个 pages.json,每个发版周期在这两个文件上产生 3–5 处合并冲突;发布动作依赖某台开发机的本地环境,换人接手需要口头交接;小程序后台的版本号和 git tag 在最近 6 个版本里有 2 个不一致。
这三件事都不是技术难题,但它们每周都在消耗时间。冲突本身不贵,贵的是解冲突的人要同时知道三个端的配置语义——谁改的 appid、谁动了分包、谁把 H5 的路由模式换了。
《工程化:Vue3 + Vite、条件编译与分包》讲过条件编译和分包,那是一个端内部的工程化。端变成四个、人变成三个组之后,问题从「代码怎么组织」变成「依赖怎么约束」。这一章给一套能落地的结构,也说明它不适用的情况。
2 核心概念
2.1 包边界:让「不允许的依赖」可被拦截
定义:单仓多包(monorepo)指一个仓库里放多个包,用 pnpm workspace 串起来。三层结构:apps/ 放各端壳,只承担路由、平台专有页面与原生插件配置;packages/ 放共享层;根目录只保留 workspace 配置与脚本。
类比:apps/ 是四个门店的招牌和门面,packages/ 是四家共用的后厨。后厨不该知道门店的装修风格。
反例:packages/core 里 import 了 uni。这一个引用会让该包无法在 Node 环境跑单测,也无法被服务端复用;污染进入主干后,清理成本随引用数量线性上升。图 12-1 里那条虚线边就是它。
图 12-1 包依赖方向与那条被禁止的边
如图 12-1 所示,依赖是单向的:壳依赖共享层,共享层之间不允许回指。这条规则的价值不在图好看,在于它可以变成 CI 里的一条 grep——命中就让流水线失败。
2.2 共享包不产出 dist
定义:共享包直接暴露 TypeScript / Vue 源码,不预先编译成 ESM。因为 uni-app 的编译发生在 Vite 插件阶段,pages.json 驱动的路由、#ifdef 条件编译、rpx 单位换算都必须在源码上完成。
反例:为缩短 CI 时间,把 packages/* 预编译成 dist 再引用。H5 端通常看不出问题,小程序端以条件编译失效、rpx 失真两种形式出现,回归用例难以稳定复现,最后被归因为「偶发样式错乱」。
这个决定的代价是构建变慢:三端并行构建在 4C8G Runner 上 6–8 分钟(pnpm 缓存命中),冷缓存时可以到 15 分钟以上。
2.3 三类差异,三个载体
定义:多端项目里的差异只有三类——平台差异、环境差异、渠道差异。它们必须落在三个不同的载体上,混放是渠道包事故的主要来源,对照见表 12-1。
表 12-1 差异类型与正确载体
| 差异类型 | 正确载体 | 典型例子 | 用错的后果 |
|---|---|---|---|
| 平台差异 | 条件编译 #ifdef MP-WEIXIN | 微信登录、支付宝支付、原生分享 | 无关代码进入产物,主包体积超限 |
| 环境差异 | .env.[mode] + VITE_ 前缀 | 测试、预发、生产的接口域名 | 改域名要重新发版 |
| 渠道差异 | 构建期脚本注入 | 同一端多个 appid、多个包名 | 手工改 manifest,必错一次 |
第三行是分发环节的高发点:manifest.json 不支持读取环境变量,而一个平台常要出多个包(微信正式号与体验号、支付宝不同主体、Android 多渠道)。手工改一次,就有一个版本会提错主体。
2.4 自动化边界:上传不等于发布
定义:小程序侧的自动化能到「上传代码、生成体验版」,提审和发布仍是人工动作;App 侧的整包发布官方明确要求经 HBuilderX 云打包。两端的自动化能力不对等。
所以流水线的终点不是「发布成功」,而是「产物已上传,等人确认」。这个边界必须写进发布单,否则 CI 静默结束、没人跟进,活动窗口就错过了。
3 动手实践
任务:搭出三层结构,把渠道 appid 注入和版本号收敛做完,再跑通一条到上传为止的流水线。
3.1 目录与 workspace 配置
mkdir -p apps/{mp-weixin,app,h5,harmony} packages/{core,api,ui,platform}
printf 'packages:\n - "apps/*"\n - "packages/*"\n' > pnpm-workspace.yaml
tree -L 2 -d运行结果:
.
├── apps
│ ├── app
│ ├── h5
│ ├── harmony
│ └── mp-weixin
└── packages
├── api
├── core
├── platform
└── ui
10 directories3.2 配置解析规则,让构建能过
// apps/mp-weixin/vite.config.ts —— @dcloudio/vite-plugin-uni
import { defineConfig } from 'vite'
import uni from '@dcloudio/vite-plugin-uni'
export default defineConfig({
plugins: [uni()],
optimizeDeps: {
// workspace 包是 TS/Vue 源码,交给 uni 编译链处理,不让 esbuild 预打包
exclude: ['@acme/core', '@acme/api', '@acme/ui', '@acme/platform']
},
server: { fs: { allow: ['..'] } } // pnpm 软链到仓库根,dev server 需放行
})预期输出(漏配 exclude 时的报错,指向的却不是依赖链):
Error: Failed to resolve entry for package "@acme/core".
# 真实原因是 esbuild 把源码当成了已编译产物仓库根还要有 .npmrc:
node-linker=hoisted预期输出(默认 symlink 结构下小程序编译器的报错):
Cannot find module '@acme/ui' from 'miniprogram/...'
# 摊平成实体目录后消失;代价是磁盘占用增加,用空间换确定性这一条我们花了 4.5 小时才定位到。报错文本只有「模块未找到」,既不指向依赖链也不提示原因。
3.3 渠道 appid 在构建期注入
// scripts/inject-manifest.mjs
import { readFileSync, writeFileSync } from 'node:fs'
import { parseArgs } from 'node:util'
const { values } = parseArgs({ options: { platform: { type: 'string' }, appid: { type: 'string' } } })
const file = `apps/${values.platform}/manifest.json`
// manifest.json 是 JSONC:允许 // 与 /* */ 注释,允许尾逗号
const strip = (s) => s.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:])\/\/.*$/gm, '$1')
const manifest = JSON.parse(strip(readFileSync(file, 'utf8')))
const target = { 'mp-weixin': 'mp-weixin', 'mp-alipay': 'mp-alipay', app: 'app-plus' }[values.platform]
if (!target) throw new Error(`[inject] 不支持的平台:${values.platform}`)
manifest[target] ??= {}
manifest[target].appid = values.appid
writeFileSync(file, JSON.stringify(manifest, null, 2), 'utf8')
console.log(`[inject] ${values.platform} appid -> ${values.appid}`)运行结果:
node scripts/inject-manifest.mjs --platform mp-weixin --appid wx8f2c1a4d9e0b
# [inject] mp-weixin appid -> wx8f2c1a4d9e0b这段脚本有一处只有跑过才知道的地方:新建工程模板的 manifest.json 自带注释,直接 JSON.parse 抛的是 Unexpected token /,行号指向注释起点,第一次容易误判成文件编码问题。剥离注释的正则还必须把 // 前紧邻的 : 排除,否则 https:// 会被截断——截断后构建照样成功,产物里的接口地址是错的,提审前不会报任何异常。
3.4 一条跑到上传为止的流水线
# .github/workflows/release.yml(节选)
jobs:
release:
runs-on: [self-hosted, linux, miniprogram] # 小程序后台有 IP 白名单,托管 Runner 出口 IP 不固定
steps:
- uses: actions/checkout@v4
- run: pnpm install --frozen-lockfile
- run: node scripts/inject-manifest.mjs --platform mp-weixin --appid ${{ vars.MP_APPID }}
- run: pnpm --filter @acme/mp-weixin build:mp-weixin
- run: node scripts/check-appid.mjs # 构建后断言 appid 与预期一致
- run: npx miniprogram-ci upload --pp ./apps/mp-weixin/dist
env:
PRIVATE_KEY: ${{ secrets.MP_PRIVATE_KEY_B64 }}运行结果(成功的一次,注意最后一行):
[inject] mp-weixin appid -> wx8f2c1a4d9e0b
build:mp-weixin done in 214s
appid 校验通过
upload ok version=1.4.0 desc=release-1.4.0
✓ 体验版已生成:请到后台提交审核(人工步骤)两个基础设施约束要预留时间:小程序后台代码上传默认开启 IP 白名单,托管 Runner 的出口 IP 是动态的,需要申请自建 Runner 或登记网段;secrets 里保存 PEM 内容时换行常被吞掉,表现为签名失败而报错不提示密钥问题,用 base64 还原比 echo 稳。
3.5 版本号只有一个来源
# tag 是唯一事实来源,versionCode 由版本号推导(示例:1.4.0 -> 140)
TAG=$(git describe --tags --abbrev=0) # v1.4.0
VER=${TAG#v}
CODE=$(echo "$VER" | awk -F. '{printf "%d%02d%02d", $1, $2, $3}')
node scripts/set-version.mjs "$VER" "$CODE"运行结果:
[version] package.json 1.4.0 / manifest.json versionName 1.4.0 versionCode 140
[version] 与 tag v1.4.0 一致versionCode 只增不减,回滚同样递增,否则客户端判定「不比本地新」直接跳过更新。这一条比版本号对齐更容易出事:回滚时把 versionCode 改回去,用户就卡在旧版本上。
3.6 分四期落地,每期有验收标准
结构一次性改完最容易翻车,我们分四期,每期两周,验收标准见表 12-2。
表 12-2 分期里程碑与验收标准
| 阶段 | 交付物 | 验收标准 |
|---|---|---|
| 一期 | 三层目录、依赖规则脚本 | packages/core 中 uni 引用数为 0,违规提交被 CI 拒绝 |
| 二期 | 渠道注入脚本、版本单一来源 | 三端产物 appid 与预期一致;缺环境变量时构建失败而非运行时 undefined |
| 三期 | 分端流水线 | 连续 10 次发布上传成功率 ≥ 95%,人工介入 ≤ 2 次 |
| 四期 | 灰度与回滚演练 | 小程序版本回退、App 整包、wgt 三条路径各演练 1 次,单次回滚 ≤ 15 分钟 |
一期的验收标准故意写成「引用数为 0」而不是「结构清晰」。能数出来的指标才能进 CI,进不了 CI 的规则三个月后一定腐化。
四期里最容易省掉的是回滚演练,而它恰恰是唯一在事故当天用得上的能力。三条路径各有各的坑:小程序要在后台切回旧版本,App 整包要重新提审,wgt 热更新要按设备哈希分批且保留上一版包体。
还有三项没定,评审时要明确责任人和时限:自建 Runner 的固定 IP 尚未申请,当前临时放开了白名单网段,安全评审未通过;App 端 wgt 热更新是否纳入本方案范围未定,截至 2026 年 11 月它只能承载 JS、CSS 与静态资源;支付宝与抖音的上传接口稳定性没有验证,目前只走微信侧的完整链路,其余平台按人工上传。
4 常见误解
以为共享包预编译成 dist 能提速。 短期能,长期会以条件编译失效和 rpx 失真回来找你,而且回归用例难以稳定复现。速度应该从缓存和并行拿,不从预编译拿。
以为 CI 上传成功就是发布完成。 上传只生成体验版。提审、发布、灰度都是人工动作,流水线要在最后一步明确打印「等人确认」,否则没人知道该谁动手。
以为拆成多仓更独立。 团队完全独立、发版节奏差异大时才对。共享包改动要走发版、升级、回归三轮,联调成本比解冲突高。
以为分层是为了目录整齐。 分层的唯一目的是把「不允许的依赖」变成可拦截的规则。目录整齐是副产品,能拦住违规提交才是收益。
5 小结
- 《进阶:适配鸿蒙 NEXT 与上架》让四个端都能出包,这一章让四个端能同时被三个组改。问题从代码组织变成依赖约束。
- 三层结构:
apps/只放壳,packages/放共享,根目录只放 workspace 配置。core不许引用uni,这条要变成 CI 检查。 - 共享包直接暴露源码。条件编译、
rpx、路由都发生在 Vite 插件阶段,预编译会把它们提前固化。 - 三类差异三个载体:平台差异用
#ifdef,环境差异用.env.[mode],渠道差异用构建期注入,并在日志里打印注入值。 - 自动化止于「上传成功、体验版已生成」。提审和发布是人工动作,写进发布单;自建 Runner 的固定 IP 与密钥换行是两个必须先解决的基础设施问题。
- 版本号单一来源是 git tag,
versionCode只增不减,回滚也递增。
6 相关文章
这是这个类目的收尾篇。从《uni-app 入门:工程结构、运行机制与多端差异》的工程结构,到《支付与交易:多端支付集成与对账》的支付、《消息与推送:订阅消息、uni-push 与厂商通道》的推送、《离线优先:缓存、同步与冲突处理》的离线、《进阶:适配鸿蒙 NEXT 与上架》的鸿蒙,再到这一篇的工程治理——四个端、一条链路、一套发布流程,已经能支撑一个真实项目从开发走到上架。
四端之外还有一条路:如果原生渲染的性能成为瓶颈,可以看 uni-app x 与 UTS 那一篇。返回类目首页:UniApp 跨平台。