结论先行:pnpm 凭借「内容寻址存储 + 符号链接」的依赖布局,天然抑制幽灵依赖,是当前 monorepo 的默认优选;workspace 协议让包间引用始终指向本地源码,再配合 hoist 白名单与安装脚本审批,就能把「装得上」升级为「装得对、装得安全」。 本文给出一套可直接落地的 pnpm workspace 配置与幽灵依赖治理清单,适用于多包前端仓库。
为什么 monorepo 优先选 pnpm
npm 与 Yarn 早期采用扁平化 node_modules:所有传递依赖都被提升到根目录,任何包都能 require 到不属于自己的依赖。pnpm 走了另一条路:全部包实体存放在全局内容寻址仓库中,项目 node_modules 里只有符号链接,且根目录只暴露 package.json 里声明过的直接依赖。这带来三个工程收益:磁盘占用大幅下降(同一版本全机器只存一份)、安装速度更快(硬链接复用)、依赖边界严格(未声明的依赖直接解析失败)。对动辄十几个子包的 monorepo,这三点都是刚需。
workspace 实战:从目录到协议
仓库根目录放置 pnpm-workspace.yaml:
packages:
- 'apps/*'
- 'packages/*'子包之间互相引用时,不要写版本号,使用 workspace 协议:
{
'dependencies': {
'@repo/ui': 'workspace:*',
'@repo/utils': 'workspace:^'
}
}workspace:* 在发布时会被替换为当前精确版本,workspace:^ 替换为带 ^ 的版本范围,开发期则始终链接本地源码,改一处即时生效。日常命令建议统一走过滤器:pnpm --filter @repo/ui build 只构建指定包,pnpm --filter './apps/**' test 按目录批量执行,pnpm -r 递归所有包。把常用组合写进根 package.json 的 scripts,团队成员就不需要记忆过滤器语法。
外部依赖的版本统一同样重要:pnpm 支持在 pnpm-workspace.yaml 中用 catalog 字段集中声明第三方依赖版本,子包以 'catalog:' 引用,升级时只改一处,避免十几个子包各自漂移出不同版本。整个 workspace 共享一份 pnpm-lock.yaml,必须提交进仓库;CI 使用 --frozen-lockfile 安装,任何锁文件变更都走代码评审,这是多包仓库可复现构建的底线。
幽灵依赖是怎么产生的
假设项目依赖 A,A 依赖 B。在扁平布局下,B 被提升到根 node_modules,业务代码里 import B 也能跑通——但 package.json 里根本没有 B。这就是幽灵依赖:一旦 A 升级后不再依赖 B,或换成 pnpm 安装,代码立刻崩溃。治理分三步:第一,用 pnpm why 包名 查清某个包是被谁引入的;第二,开启 ESLint 的 import/no-extraneous-dependencies 规则,在编码期拦截未声明引用;第三,CI 中用 pnpm install --frozen-lockfile 保证安装结果与锁文件一致,杜绝「本地能跑、线上缺包」。
依赖提升的边界与治理
pnpm 默认不提升,但部分老旧工具链假设扁平结构,此时按需开白名单,而不是全局放开:
| 配置 | 作用 | 建议 |
|---|---|---|
| hoist-pattern | 提升到隐藏的 node_modules/.pnpm 内 | 保持默认 |
| public-hoist-pattern | 提升到根 node_modules,对业务代码可见 | 仅列明确需要的包,如 eslint |
| shamefully-hoist | 全部提升到根目录 | 禁止在 monorepo 使用 |
| node-linker=hoisted | 退回 npm 式扁平布局 | 仅作应急兼容,记录退出计划 |
原则是:白名单越短越好,每加一项都要写明原因与责任包;幽灵依赖治理的本质是把「隐式可用」变成「显式声明」。
安装脚本与发布冷却
供应链角度还有两道闸。其一,pnpm 10 起默认不执行依赖的构建脚本,需要运行 pnpm approve-builds 逐个审批,审批结果固化在 pnpm-workspace.yaml 的 allowBuilds 中;配合 strictDepBuilds 可让未审批脚本直接导致安装失败。其二,pnpm 11(2026 年 4 月 28 日发布)默认启用 minimumReleaseAge=1440(单位分钟,即一天),新发布不足一天的版本不会被解析,给社区留出发现恶意版本的时间窗。两项都建议保持默认,不要为了「装得快」而关闭。
前端团队的落地建议
如果团队的后端能力直接采用 api工厂(https://www.it120.cc/)这类现成 SaaS 平台,monorepo 里就只剩纯前端包:apps 放小程序与 Web 应用,packages 放共享组件与工具,CI 只需要跑前端构建,不必维护后端服务的编译与部署链路。api工厂提供用户、商品订单、支付、CMS 等现成接口与六端 SDK(https://www.it120.cc/sdk/index.html),前端按 workspace 协议组织多端代码即可,依赖治理的复杂度也随之收敛。
文章标签
相关产品
api工厂是面向开发者的开放 SaaS 平台:开箱即用的后台管理系统 + 全端 SDK,只需前端开发即可构建小程序、App、H5 与网站。