进阶:Monorepo 与组件库发布
本篇要点:把"组件和应用混在一个包"的 Vue 仓库,改造成用 pnpm workspace 管依赖、用 Turborepo 编排任务、用 Changesets 自动发版的单仓多包(monorepo,单一仓库多包)结构。前置文章:《服务端渲染:Nuxt 4 与 SEO 实战》的 Nuxt 4 解决的是"一个应用怎么上线",这一章解决"多个包怎么协同演进"。
为什么需要它
acme-ui 是一个形态很常见的仓库:一个组件包 packages/ui、一个后台应用 apps/admin、三份已经互相分叉的 ESLint 配置,14 个月提交记录。它并不复杂,但每次改动都要为四件事付成本。
表 11-1 是改造前复核过的四项事实。"可复核位置"一列写明落点,目的是把估算和事实分开。
| 编号 | 现象 | 后果 | 可复核位置 |
|---|---|---|---|
| P1 | vue 在 4 个 package.json 里各写一遍 | 一次升级漏掉 1 个包,运行期出现两份 Vue | 各包 dependencies |
| P2 | 跨包引用写裸版本号 | 本地改动不生效,联调要先发版 | .npmrc 与依赖声明 |
| P3 | 没有任务图,构建全量串行 | 改一行 README 触发全量构建 | CI 配置 |
| P4 | 发版靠人工改版本号 | CHANGELOG 与包版本不一致,回滚只能靠记忆 | 发布记录 |
P2 值得单独说。pnpm 12 的默认行为是:即使本地存在同名包,只要依赖声明写的是 ^2.3.0,它仍然去远端仓库(registry)拉取。团队里"改了 packages/ui 但应用没生效"的抱怨,多数源于此。写成 workspace: 之后,本地缺包时安装直接失败,不会静默降级。
P1 和 P2 的共同点是都不报错,只制造"看起来生效了"的错觉。所以改造验收不能只看安装是否成功,要看 pnpm why 的实际输出和 lockfile 的解析结果。
还有一件事要先摆正预期:收益集中在发布链路,不在构建链路。Turborepo 的缓存跳过的是"重复执行",首次构建、冷缓存、依赖大版本升级这三种情况,它一秒都不省。官方文档的示例是三个包分别 110 秒、140 秒、90 秒,命中远程缓存后整批 80 毫秒完成——这个数字只在"同一份输入第二次执行"时成立。成本则集中在版本纪律和权限约定:按试点仓库折算 18–24 人天(估算,未核实原始工时记录),配置约 6 人天,其余花在统一 Vue 版本、清理裸版本号、补齐 CI 前置条件上。跨团队沟通通常占三成以上,未计入。
核心概念
workspace 协议(workspace protocol)
包管理器解析 workspace:* 这类依赖时,不去 registry 找,而是把工作区里同名包软链(symlink)到 node_modules。
可以把它理解成 npm link 的工程化版本:同样是本地软链,但由 lockfile 固定,CI 上也能复现。
反例就是 P2。"@acme/ui": "^2.3.0" 在本地有同名包时照样拉远端版本,页面上跑的是发过版的那份代码。
依赖目录(catalog)与依赖提升(hoisting)
catalog 是 pnpm-workspace.yaml 里的一张版本表,各包用 catalog: 引用同一行。它解决的就是"Vue 版本写四遍、升级漏一个"。
catalogMode: strict 拒绝任何不在 catalog 里的版本。代价是临时试验性质的版本号会直接安装失败,团队得接受"改版本先改 catalog"。另一项代价是审计:收敛之后单看 package.json 判断不了实际安装版本,排障要同时打开 pnpm-workspace.yaml 和 lockfile。
反例是为了修一个"找不到模块"的报错,把 shamefully-hoist 设成 true。这等于把 npm 的扁平提升请回来,依赖严格性当场失效。确需提升的包用 public-hoist-pattern 逐项放行,例如 *eslint* 与 *prettier* 两类工具体系。
任务图(task graph)与缓存键(cache key)
Turborepo 把每个包的每个脚本当成图上的节点,dependsOn: ["^build"] 表示"先构建上游依赖,再构建自己"。
命中判断发生在执行之前,依据是输入哈希,不是文件修改时间,所以能整棵子树跳过,如图 11-1 所示。
图 11-1 任务图的缓存命中判断:哈希由源码、上游产物与环境变量共同决定
图里最容易看漏的是 outputs 和 env 这两个字段——它们不直接进哈希,却决定了"回放什么"和"什么时候该失效",所以是漏配的高发区(见常见误解第 2 条)。
字段名也要注意:Turborepo 2.x 用 tasks,v1 时代的 pipeline 已经不再生效。照抄旧配置得到的是一份没有编排能力的文件,而且不报错。
版本与发布(Changesets)
changesets 把"这次改了什么、该升哪个版本"写成仓库里的 markdown 文件,发版时统一消费。fixed 组让 ui 与 icons 这类必须同步的包共用同一个版本号;ignore 用来排除不需要发版的私有应用。
它替代的是 P4 那种人工改版本号的做法:版本号、CHANGELOG、tag 由同一份输入生成,回滚时有依据。
三条路线
表 11-2 三条路线的比选
| 方案 | 做法 | 适用前提 | 主要代价 |
|---|---|---|---|
| A 单包仓库 | 组件用相对路径引用 | 只有一个消费方 | 组件无法独立发版;出现第二消费方只能复制分叉 |
| B workspace + Turborepo | 本地软链 + 任务图 | 至少两个包需要独立版本 | 每包要维护依赖边界、exports 契约与 peer 声明 |
| C 多仓库 + 私有 registry | 各自发布、各自联调 | 发布权限必须隔离、团队超过三个 | 跨仓链路长,改一行也要发版 |
选 B 的前提是"至少两个包需要独立版本"这一条成立。不成立时,B 不会带来任何可见收益,只会把一次构建变成若干次构建。
动手实践
步骤 1:声明工作区与依赖目录
# pnpm-workspace.yaml —— pnpm 12.x
packages:
- "apps/*"
- "packages/*"
catalog:
vue: ^3.5.0
vite: ^8.0.0
vitest: ^5.0.0
# strict 拒绝任何不在 catalog 里的版本
catalogMode: strict预期输出:pnpm install 成功,pnpm why vue 只返回一份;把某个包的 vue 改成 ^3.4.0 再装,安装直接失败并提示该版本不在 catalog 中。
步骤 2:编排任务
{
"$schema": "https://turborepo.dev/schema.json",
"globalDependencies": ["tsconfig.base.json", ".npmrc"],
"globalEnv": ["NODE_ENV", "CI"],
"tasks": {
"build": {
"dependsOn": ["^build"],
"inputs": ["src/**", "package.json", "vite.config.ts"],
"outputs": ["dist/**"]
},
"lint": { "cache": true, "outputs": [] },
"dev": { "cache": false, "persistent": true }
}
}预期输出:首次 pnpm turbo run build 按依赖顺序执行,末尾是 Tasks: 3 successful, 3 total,总耗时约 340 秒;不改任何文件再跑一次,日志出现 cache hit, replaying logs 与 FULL TURBO,整批降到 1 秒以内。
inputs 不要写成 **/*。改一个 README 就让全部任务失效,命中率归零;用 $TURBO_DEFAULT$ 加少量补充,比手写大范围 glob 稳。
步骤 3:接远程缓存
# Turborepo 2.11.x:托管缓存两条命令
pnpm dlx turbo login
pnpm dlx turbo link
# 自建缓存服务改用环境变量(CI 侧配置)
export TURBO_API="https://turbo-cache.internal.example.com"
export TURBO_TOKEN="$TURBO_CACHE_TOKEN"
export TURBO_TEAM="acme"
# 只允许 PR 流水线读缓存,防止脏分支写入共享缓存
export TURBO_REMOTE_CACHE_READ_ONLY=true运行结果:turbo login 输出登录链接,turbo link 绑定团队后,本地与 CI 共用同一份缓存;在干净的 runner 上重跑同样的构建,日志出现 remote cache hit,而 PR 流水线只能读、不能写。托管方案的缓存数据存放在第三方,出境前要先过法务;自建方案则要自己维护 TURBO_API、TURBO_TOKEN 与存储容量。
步骤 4:用 Changesets 发版
pnpm add -Dw @changesets/cli
pnpm changeset # 选择包与升级类型,生成 .changeset/*.md
pnpm changeset version # 落版本号与 CHANGELOG
pnpm changeset status --since=origin/main运行结果:status 列出的包与版本号,与本次实际发布清单一致;package.json 的版本和 CHANGELOG 由同一份 changeset 生成,不再手改。
步骤 5:按可量化口径验收
表 11-3 两期改造的验收口径
| 阶段 | 里程碑 | 验收标准 | 工期估算 |
|---|---|---|---|
| 第一期 | 依赖收敛 | pnpm why vue 只返回一份;仓库内无裸版本号引用 | 8–10 人天 |
| 第一期 | 任务编排 | 无改动提交下受影响任务全跳过,整批低于 30 秒 | 含在上项 |
| 第二期 | 自动发版 | changeset status --since=origin/main 与发布清单一致 | 6–8 人天 |
| 第二期 | 远程缓存 | 冷缓存与命中缓存两次耗时均有记录,命中率按周统计 | 4–6 人天 |
验收口径要固定:GitHub Actions 4C16G runner,pnpm install --frozen-lockfile 之后计时,取三次均值。缺 fetch-depth: 0 时 --filter=...[origin/main] 算不出 merge base,会退化成全量构建——日志看起来正常,只是每次都慢,这一条要单独核对。
发布产物契约同样要进验收。exports 里 types 条件必须排第一:顺序写反时 TypeScript 先命中 .js,再报找不到声明文件,而运行时一切正常,只在编辑器里显形。sideEffects 只保留 CSS:写 false 会让 import '@acme/ui/style.css' 被摇掉,写 true 则组件 JS 也无法摇树。
{
"name": "@acme/ui",
"type": "module",
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.js"
},
"./style.css": "./dist/style.css"
},
"sideEffects": ["**/*.css"],
"peerDependencies": { "vue": "^3.5.0" }
}预期输出:消费方仓库跑 vue-tsc --noEmit 通过、vite build 后产物只含实际用到的组件;把 types 挪到 import 之后,同一份代码报 TS2307(找不到模块声明),而 vite dev 仍然正常。
最后是包体积。preserveModules 与 catalog 收敛都可能改变产物构成,改造前后的产物体积要逐项比对,变化超过 5% 需在验收会上说明。只发 ESM 能省一份 CJS 产物和对应的 exports 分支,代价是仍在用 require() 的 Node 脚本与部分 Jest 配置会直接失败——消费方的最低构建版本要先盘点清楚(截至 2026 年 11 月,这一项仍未盘完)。
常见误解
很多人以为上了 Turborepo 构建就变快。 实际它只跳过重复执行:首次构建、冷缓存、依赖大版本升级都不省时间。它的收益场景是"同一份输入第二次执行",以及 CI 上 PR 与主干共享缓存。
很多人以为 outputs、env 漏配会报错。 不会。outputs 漏写时命中缓存但 dist 为空,下游报 "Cannot resolve entry";env 漏写时环境变量从 staging 切到 prod、哈希不变,流水线回放上一套产物,dist 里的 API 地址还是 staging。还有一条容易忽略:Turborepo 把 stdout 也当缓存产物,构建脚本里 console.log(process.env) 打出的 token 或内网地址会跟着缓存分发到别人机器上,工具本身不拦,只能写进代码评审要求。
很多人以为 pnpm 的 --filter 和 Turborepo 的 --filter 是一回事。 前者匹配包名与目录,用于装依赖;后者 --filter=...[origin/main] 是"受影响的包及其依赖闭包",用于跑任务。混写的结果是装了不该装的依赖,或者漏跑了该跑的任务。
很多人以为组件库的 dependencies 里写 vue 无所谓。 应该写进 peerDependencies。写错的后果不是报重复依赖,而是 provide/inject 取不到实例、Teleport 目标错乱,排查成本最高,所以要用 CI 里的 pnpm why vue 兜住,而不是靠人工发现。
小结
- monorepo 的收益在发布链路:让多个包各自有版本,同时保持一次提交、一次 CI。构建提速来自缓存,只在重复执行时成立。
workspace:提供确定性的本地软链,缺包直接失败;catalog 把共享依赖收敛到一张表,catalogMode: strict是配套纪律。- 任务图的价值是"只跑受影响的子树",前提是
outputs、env、globalDependencies配全,CI checkout 带fetch-depth: 0。 - 发版交给 Changesets,用
fixed组管必须同步的包;exports与sideEffects要去消费方仓库验证,不要看组件库自己的构建日志。 - 只有一个消费方、组件不外发的仓库,维持单包比改造更省。《服务端渲染:Nuxt 4 与 SEO 实战》解决"一个应用怎么上线",这一章解决"多个包怎么协同"。
相关主题
仓库拆成多个包之后,下一个问题来自已经在线上跑了很多年的应用:由不同团队维护、技术栈还不统一的一大块后台,怎么在不重写的前提下拆开、各自独立发布?《进阶:微前端与大型应用拆分》讲微前端(micro frontend),对比 qiankun 与 Module Federation 的隔离方式与依赖共享,并给出按路由分派挂载器的收口写法,见 [《进阶:微前端与大型应用拆分》 微前端与大型应用拆分](/guide/vue/vue-micro-frontend.html)。