Lerna 移除 bootstrap/add/link 之后全面迁移到包管理器 Workspaces 的实战指南【免费下载链接】lernaLerna is a fast, modern build system for managing and publishing multiple JavaScript/TypeScript packages from the same repository.项目地址: https://gitcode.com/gh_mirrors/le/lerna导读自 2023 年 6 月 Lerna v7.0.0 起lerna bootstrap、lerna add与lerna link三个命令被默认移除经过两年多的弃用期Lerna v9.0.02025 年 9 月发布终于彻底删除了它们。本指南以官方文档 website/docs/legacy-package-management.md 为主体结合当前仓库Lerna 10.x的源码与变更记录系统讲解这些命令曾经做了什么、为什么必须退役、如何用 npm/yarn/pnpm 的workspaces特性逐条替换以及自定义 hoisting 场景下的迁移策略。读完本文你将掌握一套可直接落地的 monorepo 现代化迁移方案。一、背景为什么这三个命令必须退役Lerna 是 JavaScript 生态中最早的 monorepo/workspace 工具。2015/2016 年它诞生时npm、yarn、pnpm 都还没有内建的workspace多包单仓能力因此lerna bootstrap安装外部依赖并链接内部包、lerna add向工作区包添加依赖、lerna link仅执行内部链接曾是 Lerna 的核心能力也是当时唯一的选择。然而现状早已改变npm、yarn、pnpm如今都把 workspaces 作为一等公民first-class特性经过多年实战打磨它们在添加、移除、链接本地包以及与第三方依赖自然组合上的实现已相当成熟。重复造轮子不再有意义。正如文档所述Lerna 前任维护者 Daniel 在其任期最后几年一直在鼓励社区重新审视这些命令2022 年接手项目的新维护团队在近距离了解现状后也完全认同安装与链接依赖不是 Lerna 的职责包管理器做得更好。移除这些遗留命令后社区可以把精力集中在 Lerna 最有价值的领域——版本管理与发布versioning and publishing。这一点在当前仓库的命令注册表中可以得到直接印证。查看 packages/lerna/src/index.tsLerna 10.x 实际注册的命令是add-caching、changed、clean、create、diff、exec、import、info、init、list、publish、repair、run、watch、version——bootstrap、add、link均不在其中。移除时间线与事实依据v7.0.02023 年 6 月三个命令默认移除改用lerna/legacy-package-management包提供临时 polyfill。仓库根 CHANGELOG.md 中明确记录We no longer include thebootstrap,add, andlinkcommands by default. We strongly recommend using your package manager (npm,yarn,pnpm) for package management related concerns对应do not include bootstrap, add, link commands by default条目。v9.0.02025 年 9 月lerna/legacy-package-management正式移除。仓库根 CHANGELOG.md 记录The lerna/legacy-package-management package has been formally removed after 2 years of deprecation。v9 及以后执行这些命令会怎样虽然命令被删除但为了给误用者清晰反馈Lerna 在 packages/lerna/src/index.ts 中为add、bootstrap、link注册了三个壳命令shell commands它们会解析并接受所有参数避免 yargs 直接报参数校验错误随后输出错误日志The bootstrap command was removed by default in v7 with a notice that it was no longer maintained. In v9, over 2 years later, it was finally removed.并引导用户查阅本文档https://lerna.js.org/docs/legacy-package-management最后以退出码 1 结束。也就是说任何调用都会立即失败并给出迁移指引而不会静默执行任何操作。二、核心思路转变让包管理器接管安装与链接迁移前请先完成一个关键的心智转变Lerna 不负责在你的仓库中安装和链接依赖包管理器更适合这项任务。实现方式就是启用包管理器的workspaces特性npm在根package.json中声明workspaces字段yarn配置workspacesYarn v1 的workspaces字段或 Yarn v3 的.yarnrc.ymlpnpm使用pnpm-workspace.yaml启用workspaces后包管理器会在install命令中内建执行原先lerna bootstrap/lerna link所做的工作——即把工作区内的本地包相互链接通常是符号链接并将第三方依赖提升到合适层级。无需在安装后再跑任何附加命令前提是workspaces已按各包管理器文档正确配置。lerna add的职责同样已被覆盖添加/移除依赖本来就是包管理器的工作而由于 workspaces 是一等公民用例你只需对指定 workspace 执行一次install类命令所有相关的本地链接都会自动完成。事实上Lerna 项目自己就在吃自己的狗粮根 package.json 声明了workspaces: [packages/lerna, website]依赖管理完全交由 npm 负责Lerna 自身只专注于版本发布与任务编排。三、替换lerna bootstrap/lerna link它原本做什么lerna bootstrap代替npm install或yarn/pnpm负责安装全部外部依赖并在工作区内链接所有内部包。lerna link只执行其中内部链接这一步。通常在哪里能找到它大概率出现在工作区根目录package.json的scripts字段中同时务必检查 CI 流水线——很多流水线会用lerna bootstrap代替npm install。用什么替换原命令替换方案lerna bootstrapnpm install或yarn/pnpm对应安装命令lerna link直接删除链接步骤已由包管理器在安装时完成如果工作流中在原来调用lerna bootstrap的位置之前已经执行过包管理器的 install 命令那么直接把lerna bootstrap删掉即可不必重复安装。yarn 用户注意如果依赖 bin 链接切换到 workspaces 后可能需要一次性删除node_modules文件夹再重新安装以清理旧链接结构。源码佐证bootstrap曾经如何工作虽然实现已移除但仓库根 CHANGELOG.md 保留了大量历史记录可以还原其复杂度这也解释了为什么维护者认为应该退休bootstrap曾经需要处理 lifecycle 脚本的拓扑排序执行Run install lifecycles only once-per-package, in topological order、hoisting--hoist/--nohoist、--force-local、循环依赖检测--reject-cycles、与 yarn workspaces 的兼容告警、--strict选项等。这些职责全部是包管理器已内建或应内建的能力由 npm/yarn/pnpm 统一维护显然更可靠。四、替换lerna add它原本做什么lerna add用于向工作区内的包添加依赖会逐一更新每个包的package.json。通常在哪里能找到它虽然多为手动调用但也可能出现在根package.json的scripts中。用什么替换最常见的使用场景是向工作区内单个包添加单个依赖原来的写法lerna add dependency --scope package可直接替换为npm install dependency -w package-w--workspace标志告诉 npm 只在package指定的工作区包内安装该依赖作用与 Lerna 的--scope选项类似。如果需要向多个包添加依赖可以多次使用-wnpm install dependency -w package1 -w package2各包管理器的等价写法yarnyarn workspace package add dependencyYarn v1/v3 均支持pnpmpnpm --filter package add dependency添加完成后本地包之间的链接会自动建立无需像旧工作流那样再手动执行lerna bootstrap或lerna link。五、自定义 Hoisting 场景迁移策略lerna bootstrap遗留能力中最让人不舍的一点是 hoisting 控制——可以决定某些依赖是否提升到仓库根目录的node_modules或保留在嵌套位置。针对自定义 hoisting 需求文档给出以下经验结论来自维护团队实测现代 yarnv3 及以后提供了最灵活的 hoisting 控制核心配置项为nmHoistingLimitsworkspaces/dependencies/none可精确限制 node_modules 的提升层级。到目前为止无论 hoisting 多复杂还没有发现无法迁移到现代 yarn 的lerna bootstrap仓库。如果你正面临这种定制场景值得先尝试迁移到现代 yarn。如果原本只是使用lerna bootstrap而未涉及高级 hoisting那么 npm、yarn、pnpm 任选其一即可它们都提供健壮的 workspaces 实现。六、v7/v8 时代的临时方案lerna/legacy-package-management如果你在 v7 或 v8 阶段确实被遗留命令卡住官方曾提供临时 polyfill安装与你lerna包同版本号的lerna/legacy-package-management包即可恢复这三个命令的旧实现。但必须强调这只是过渡方案stop gap该包自发布起即进入仅维护模式maintenance mode only——不规划任何新特性仅合并关键补丁与安全更新。v9 已移除对该包的全部支持距其作为临时 polyfill 引入已超过两年给团队留出了充足的迁移时间。仓库根 CHANGELOG.md 的 v7 条目印证了这一演进If you want to temporarily continue to use those commands in v7 you can do so by installing the lerna/legacy-package-management package at the same version as your lerna versionv9 条目则宣告The lerna/legacy-package-management package has been formally removed after 2 years of deprecation。七、迁移检查清单将上面的内容整理为可直接执行的清单定位残留调用搜索根package.json的scripts以及 CI 配置中的lerna bootstrap、lerna add、lerna link。启用 workspaces在根package.json添加workspaces: [packages/*]npm/yarn v1或按 pnpm 文档创建pnpm-workspace.yamlyarn v3 使用.yarnrc.yml的nodeLinker与nmHoistingLimits。替换 installlerna bootstrap→npm install或yarn/pnpm install若流水线已有 install 步骤直接删除。删除 linklerna link整行删除链接由安装命令内建完成。替换 addlerna add dep --scope pkg→npm install dep -w pkg多包则重复-wyarn 用yarn workspace pkg addpnpm 用pnpm --filter pkg add。验证删除node_modules与 lockfile 后全新安装一次尤其 yarn 用户确认本地包符号链接、bin 链接与依赖树符合预期。八、进一步阅读官方迁移指南原文website/docs/legacy-package-management.md本文即以其为主体展开Lerna 命令注册表与遗留命令壳实现packages/lerna/src/index.tsv7/v9 移除与 polyfill 演进记录packages/lerna/CHANGELOG.md、CHANGELOG.mdLerna 自身的 workspaces 实践package.json相关的 Lerna 6 过时选项说明任务运行维度的遗留清理website/docs/lerna6-obsolete-options.md本文档在站点侧边栏中的位置website/sidebars.js【免费下载链接】lernaLerna is a fast, modern build system for managing and publishing multiple JavaScript/TypeScript packages from the same repository.项目地址: https://gitcode.com/gh_mirrors/le/lerna创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
