Skip to content

多端项目结构与 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 配置 ​

bash
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

运行结果:

text
.
├── apps
│   ├── app
│   ├── h5
│   ├── harmony
│   └── mp-weixin
└── packages
    ├── api
    ├── core
    ├── platform
    └── ui

10 directories

3.2 配置解析规则,让构建能过 ​

ts
// 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 时的报错,指向的却不是依赖链):

text
Error: Failed to resolve entry for package "@acme/core".
# 真实原因是 esbuild 把源码当成了已编译产物

仓库根还要有 .npmrc:

ini
node-linker=hoisted

预期输出(默认 symlink 结构下小程序编译器的报错):

text
Cannot find module '@acme/ui' from 'miniprogram/...'
# 摊平成实体目录后消失;代价是磁盘占用增加,用空间换确定性

这一条我们花了 4.5 小时才定位到。报错文本只有「模块未找到」,既不指向依赖链也不提示原因。

3.3 渠道 appid 在构建期注入 ​

js
// 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}`)

运行结果:

bash
node scripts/inject-manifest.mjs --platform mp-weixin --appid wx8f2c1a4d9e0b
# [inject] mp-weixin appid -> wx8f2c1a4d9e0b

这段脚本有一处只有跑过才知道的地方:新建工程模板的 manifest.json 自带注释,直接 JSON.parse 抛的是 Unexpected token /,行号指向注释起点,第一次容易误判成文件编码问题。剥离注释的正则还必须把 // 前紧邻的 : 排除,否则 https:// 会被截断——截断后构建照样成功,产物里的接口地址是错的,提审前不会报任何异常。

3.4 一条跑到上传为止的流水线 ​

yaml
# .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 }}

运行结果(成功的一次,注意最后一行):

text
[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 版本号只有一个来源 ​

bash
# 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"

运行结果:

text
[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 小结 ​

  1. 《进阶:适配鸿蒙 NEXT 与上架》让四个端都能出包,这一章让四个端能同时被三个组改。问题从代码组织变成依赖约束。
  2. 三层结构:apps/ 只放壳,packages/ 放共享,根目录只放 workspace 配置。core 不许引用 uni,这条要变成 CI 检查。
  3. 共享包直接暴露源码。条件编译、rpx、路由都发生在 Vite 插件阶段,预编译会把它们提前固化。
  4. 三类差异三个载体:平台差异用 #ifdef,环境差异用 .env.[mode],渠道差异用构建期注入,并在日志里打印注入值。
  5. 自动化止于「上传成功、体验版已生成」。提审和发布是人工动作,写进发布单;自建 Runner 的固定 IP 与密钥换行是两个必须先解决的基础设施问题。
  6. 版本号单一来源是 git tag,versionCode 只增不减,回滚也递增。

6 相关文章 ​

这是这个类目的收尾篇。从《uni-app 入门:工程结构、运行机制与多端差异》的工程结构,到《支付与交易:多端支付集成与对账》的支付、《消息与推送:订阅消息、uni-push 与厂商通道》的推送、《离线优先:缓存、同步与冲突处理》的离线、《进阶:适配鸿蒙 NEXT 与上架》的鸿蒙,再到这一篇的工程治理——四个端、一条链路、一套发布流程,已经能支撑一个真实项目从开发走到上架。

四端之外还有一条路:如果原生渲染的性能成为瓶颈,可以看 uni-app x 与 UTS 那一篇。返回类目首页:UniApp 跨平台。