npm workspaces vs pnpm vs Lerna：从 sample-monorepo 看 monorepo 工具链怎么选

npm workspaces vs pnpm vs Lerna从 sample-monorepo 看 monorepo 工具链怎么选【免费下载链接】sample-monorepoSample monorepo setup with npm workspaces and typescript project references项目地址: https://gitcode.com/gh_mirrors/sa/sample-monorepo选择 monorepo 工具链是前端与 Node.js 团队绕不开的决策题。本文以 sample-monorepo 这个「npm workspaces TypeScript project references」的示例仓库为样本用一篇文章讲清 npm workspaces、pnpm 与 Lerna 三者的定位差异、优缺点与适用场景帮你快速确定自己的 monorepo 工具链怎么选。无论你是刚接触 monorepo 的新手还是正在纠结迁移方案的老手这份对比指南都能派上用场。为什么 monorepo 越来越流行一个项目往往由多个子包组成组件库、业务应用、后端服务。传统多仓库multi-repo模式下跨包改代码要发版、拉依赖、再联调成本极高。而 monorepo 把多个包放进同一个仓库带来三个核心收益统一依赖公共依赖只装一份版本天然对齐⚡跨包联调改完组件库代码应用立刻生效无需发布原子提交一次提交可以同时包含多个包的改动回溯更轻松而要把 monorepo 跑起来就需要一套称手的工具链。目前最主流的三个选项正是 npm workspaces、pnpm 和 Lerna。sample-monorepo一份可运行的 monorepo 教科书在纸上谈兵之前先看看 sample-monorepo 这个真实的示例仓库。它用最朴素的配置演示了 monorepo 的标准姿势非常适合当作学习样本。仓库里都有什么packages/ components/ # sample/components React 组件库 app/ # sample/app React 应用依赖 components server/ # sample/server Express 服务依赖 app含 SSR三个包互相引用app 依赖 componentsserver 又依赖 app形成一条完整的依赖链。这正是 monorepo 最典型的用法——跨包协作就在仓库内部完成。关键配置文件根目录package.json通过workspaces: [packages/*]声明工作区这是 npm workspaces 的核心配置根目录tsconfig.json使用 references 引用三个子项目配合tsconfig.base.json实现 TypeScript project references 增量构建每个包自己的packages/app/src/tsconfig.json、packages/server/src/tsconfig.json通过 extends 继承公共配置再声明各自的 outDir 与 referenceslerna.json配置了npmClient: npm、useWorkspaces: true和version: independent负责版本发布整个仓库只有一个package-lock.json所有依赖统一锁版本接下来我们就围绕这份配置逐一拆解三个工具的角色。npm workspaces开箱即用的工作区方案npm workspaces 从 npm 7 起内置不需要安装任何额外工具。sample-monorepo 选择它作为基础正是看重其零门槛的特点。npm workspaces 怎么用只需在根package.json声明工作区目录再执行npm installnpm 会自动完成三件事符号链接把packages/*下的本地包链接进根node_modules跨包 import 无需发布依赖提升公共依赖 hoist 到根目录避免重复安装单一锁文件全仓共用一份package-lock.json版本一致性好运行子包脚本也很简单比如启动 app 包npm run -w sample/app startnpm workspaces 优缺点✅ 优点零学习成本npm 自带文档多、踩坑少与 CI、云平台等生态兼容性最好配置极简一个字段搞定❌ 缺点安装速度一般磁盘占用高于 pnpm依赖提升带来的幽灵依赖phantom dependency问题较常见新版严格的 workspaces 模式要求 Node 22老项目升级有成本适合人群中小团队、希望快速起步、不想引入额外依赖的项目。pnpm workspaces硬链接与内容寻址存储的极速派如果 npm workspaces 是「够用」那 pnpm 就是「更快、更省、更严格」的进阶选择。pnpm 的核心优势内容寻址存储所有依赖放进全局 store各项目通过硬链接引用同样的包只下载一次磁盘占用极省实测大型 monorepo 可节省 50% 以上的磁盘空间严格隔离node_modules 结构更接近真实语义只有 package.json 里声明的依赖才可见从根上解决幽灵依赖pnpm 同样支持 workspaces 配置只需要把根目录的 workspaces 字段保留安装命令换成pnpm install即可无缝迁移。像 sample-monorepo 这样的结构改包管理器几乎零成本。pnpm 的注意点部分老旧工具链个别 webpack 插件、electron 构建脚本可能与严格的 node_modules 结构不兼容团队需要适应pnpm的命令习惯适合人群包数量多、依赖重、追求安装速度与磁盘效率的中大型团队。Lerna专注版本管理与发布的指挥官很多人把 Lerna 和包管理器混为一谈其实定位完全不同npm/pnpm 负责「装依赖」Lerna 负责「发版本」。Lerna 解决什么问题monorepo 里的包要分别发布到 npm这就带来两个痛点版本号怎么定、依赖关系怎么维护。Lerna 用两种模式解决固定模式fixed所有包共用一个大版本发版时一起升独立模式independent每个包各自维护版本号谁改谁发sample-monorepo 的lerna.json采用 independent 模式配合 npm workspaces 使用安装交给 npm发布交给 Lerna。发布时执行npx lerna publishLerna 会自动识别哪些包自上次发布后有改动询问新版本号并联动更新依赖方。必要时可用npx lerna publish --force-publish强制全量发布。Lerna 的定位Lerna 本身不管理依赖安装必须和 npm workspaces 或 pnpm 搭配使用。它更像 monorepo 工具链中的「发布指挥官」负责最后一步的版本编排。适合人群需要把包发布到 npm、依赖关系复杂、对版本号管理有要求的开源项目与组件库团队。三者对比一览表维度npm workspacespnpm workspacesLerna本质工作区机制包管理器 工作区版本与发布管理依赖安装内置零依赖内容寻址存储极速不负责安装磁盘占用一般最省不涉及幽灵依赖较常见严格隔离不涉及版本发布需自行处理需自行处理核心能力学习成本最低中等中等适合场景中小项目中大型项目需要发布 npm 的仓库简单说npm workspaces 管安装pnpm 是更快的安装Lerna 管发布三者完全可以组合使用。实操用 sample-monorepo 跑通 monorepo 全流程理论讲完动手验证一遍才最有说服力。sample-monorepo 仓库可以直接克隆体验执行以下命令git clone https://gitcode.com/gh_mirrors/sa/sample-monorepo cd sample-monorepo npm i npm run buildnpm i触发 workspaces 安装三个包自动链接npm run build执行根目录的tsc --build按 TypeScript project references 顺序增量构建先 components再 app最后 server依赖关系由各包的 references 自动推导构建完成后还可以体验两种运行方式npm start # 客户端 dev 模式带 source-map npm run start:server # 服务端 SSR 模式客户端先打包再渲染前后端共用一套仓库、一次安装、一次构建这就是 monorepo 工具链带来的实际体验。总结monorepo 工具链怎么选回到最初的问题我的建议很简单新手或小团队直接选 npm workspaces零成本起步先把 monorepo 跑起来追求速度与磁盘效率升级到 pnpm workspaces配置迁移几乎无感需要发布 npm 包在 npm 或 pnpm 基础上叠加 Lerna搞定版本管理️大型复杂仓库可以考虑 Turborepo、Nx 等更重的构建编排方案但那是另一个话题了monorepo 工具链没有绝对的优劣只有适不适合。像 sample-monorepo 这样先跑通最小闭环再按需演进才是最务实的路径。希望这份对比能帮你少走弯路选对工具把精力留给真正的业务开发。【免费下载链接】sample-monorepoSample monorepo setup with npm workspaces and typescript project references项目地址: https://gitcode.com/gh_mirrors/sa/sample-monorepo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考