Skip to content

进阶:Monorepo 与组件库发布 ​

本篇要点:把"组件和应用混在一个包"的 Vue 仓库,改造成用 pnpm workspace 管依赖、用 Turborepo 编排任务、用 Changesets 自动发版的单仓多包(monorepo,单一仓库多包)结构。前置文章:《服务端渲染:Nuxt 4 与 SEO 实战》的 Nuxt 4 解决的是"一个应用怎么上线",这一章解决"多个包怎么协同演进"。

为什么需要它 ​

acme-ui 是一个形态很常见的仓库:一个组件包 packages/ui、一个后台应用 apps/admin、三份已经互相分叉的 ESLint 配置,14 个月提交记录。它并不复杂,但每次改动都要为四件事付成本。

表 11-1 是改造前复核过的四项事实。"可复核位置"一列写明落点,目的是把估算和事实分开。

编号现象后果可复核位置
P1vue 在 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:声明工作区与依赖目录 ​

yaml
# 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:编排任务 ​

json
{
  "$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:接远程缓存 ​

bash
# 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 发版 ​

bash
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 也无法摇树。

json
{
  "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)。