JavaScript 包管理器选型与迁移：从现状盘点到可逆切换
团队讨论包管理器时，很容易变成“谁安装更快”的投票。这个问题太小了。一次安装同时决定依赖如何求解、哪些包在磁盘上可见、lockfile 怎样评审、workspace 如何连接、生命周期脚本是否执行、CI 能否冻结恢复，以及旧项目出现兼容问题时能不能回去。
因此选型不是排行榜，迁移也不是删除一个 lockfile 再生成另一个。合格的迁移要证明：新工具在相同 manifest、网络、凭证、平台和测试条件下产生可解释结果；失败时，团队能在一个变更窗口内恢复旧入口与旧依赖树。
你要解决的工程问题
包管理器选型要同时解决九个问题：依赖如何求解和落盘，lockfile 如何审查，workspace 如何连接，脚本按什么规则执行，生态兼容由什么证据证明，供应链和凭证怎样受控，跨平台结果是否稳定，CI 能否冻结恢复，以及退出时能否恢复旧依赖树。npm、pnpm、Yarn Modern 与 Bun package manager 的差异都应落到这些工程结果上。
如果问题只是某一种工具如何安装和配置，应进入对应的 npm、pnpm、Yarn Modern 或 Bun 操作手册；如果问题已经变成 Bun runtime、前端框架、包发布、制品库服务端，或者 Nx、Turborepo 等大仓任务图，应切换到相邻工具链处理。Yarn Classic 只作为已有项目的迁移来源，不作为新项目候选。
先选一个能暴露迁移风险的代表项目
迁移负责人需要仓库写权限、CI 试验分支、可删除缓存目录和至少两种目标平台。先选一个代表项目，而不是只用空模板。代表项目应覆盖团队真实风险：
单包或 workspace 的真实依赖图。至少一个 peer dependency 或可选平台依赖。若生产项目存在，则包含原生扩展和 install script。
私有 scope、代理、CA 或镜像。test、lint、build 和产物校验入口。Linux CI 与至少一种开发者主平台。
缺少这些项目事实，只能完成命令试用，不能形成选型结论。
安装或启用入口：候选工具必须受控分发
选型实验的第一条纪律，是不用个人全局环境替团队做结论。npm 应记录它来自哪个 Node.js 安装或独立升级；pnpm、Yarn Modern 应记录 Corepack、独立安装器或开发镜像入口；Bun 应记录官方安装器、组织软件源或 CI setup。每一种候选都要固定精确版本，并在日志中打印实际命令来源。
node --version
npm --version
pnpm --version
yarn --version
bun --version实际只运行已安装候选。命令不存在是有效盘点结果，不应临时全局安装四套工具。使用 Corepack 前查看 Node.js Corepack 说明和当前 Node.js 发布说明，确认它是否随目标 Node.js 分发、代理哪些命令以及实验状态；不能假设它会拦截 npm，也不能用它交付 Bun。正式试验应由可删除开发镜像、独立工作区或 CI 候选 job 提供工具版本。
升级候选工具前分别查看 npm 文档、pnpm 安装与兼容入口、Yarn 安装与迁移入口和 Bun 安装入口。需要确认的是目标 Node.js 支持范围、精确版本安装方法、lockfile 格式变化、平台限制和回退版本，而不是只抄一条最新安装命令。
先理解四种不同的工程取向
npm：生态默认入口
npm 常随 Node.js 提供，传统默认使用 hoisted node_modules，package-lock.json 与 npm ci形成广泛理解的冻结恢复路径。优势是上手和第三方兼容成本低；风险是工具版本容易跟随机器 Node 安装漂移，平坦目录可能掩盖幽灵依赖。升级 npm 主版本时还要重新查看 Node.js 支持范围和脚本策略，不能只比较 CLI 命令是否还存在。
pnpm：内容寻址与严格链接
pnpm 用全局内容寻址 store 复用包文件，在项目 node_modules/.pnpm 中建立硬链接与符号链接图。链接结构解释包文件、虚拟 store 和项目入口之间的关系，workspace 说明则定义 workspace: 与工作区配置。直接依赖才暴露到项目入口，能较早发现未声明依赖。优势是多项目磁盘复用和 workspace 能力；风险是旧工具、symlink、hoist 兼容和 store / lockfile 主版本约束需要团队理解。
Yarn Modern：可配置 linker 与项目级能力
Yarn linker 说明把 PnP、node-modules 和 pnpm 都列为稳定模式；默认 PnP 不代表项目必须使用 PnP。Classic 到 Modern 迁移指南还要求处理 .yarnrc.yml、命令和生命周期行为差异。它把版本入口、lockfile、插件、workspace 与安全能力组织成项目工具链，优势是可配置依赖模型和治理能力；代价是 Classic 迁移、PnP SDK、插件与配置学习成本。
Bun package manager：单二进制与高速物化
Bun package manager 可以按 bun install 说明为 Node.js 项目生成兼容 node_modules；锁文件说明定义文本 bun.lock 与旧格式迁移，isolated installs解释 hoisted / isolated 及项目历史对默认值的影响。优势是单二进制和安装性能；风险是团队容易把 package manager、script runner 和 runtime 迁移混为一谈，且生态兼容与默认安全差异必须用真实项目证明。
配置与选型矩阵：比较契约，不比较口号
| 决策面 | npm | pnpm | Yarn Modern | Bun package manager |
|---|---|---|---|---|
| 典型依赖物化 | hoisted node_modules | store + .pnpm 链接图 | PnP / pnpm / node-modules 可选 | hoisted / isolated 可选 |
| 权威锁文件 | package-lock.json | pnpm-lock.yaml | yarn.lock | bun.lock |
| 冻结恢复 | npm ci | pnpm install --frozen-lockfile | yarn install --immutable | bun ci |
| workspace 入口 | 根 package.json | pnpm-workspace.yaml | 根 package.json | 根 package.json |
| 幽灵依赖暴露 | hoisted 下较弱 | 较强，受 hoist 配置影响 | PnP 最强，其他 linker 视配置 | isolated 较强，hoisted 较弱 |
| 生命周期脚本 | 需显式治理 | 需结合版本与脚本批准策略 | 默认与安全配置会演进 | trustedDependencies 与内置允许列表 |
| 旧生态兼容 | 通常最高 | 多数兼容，链接工具需验证 | node-modules 高，PnP 需适配 | hoisted 较高，原生与脚本需验证 |
| 工具分发 | Node 携带 / 独立 npm | Corepack / 独立安装 | Corepack / 项目 binary | 官方安装器 / 软件源 / CI setup |
| 退出难度 | 基线 | 取决于 workspace、patch、catalog | 取决于 PnP、插件和 Yarn 特性 | 取决于 Bun 特性与 runtime 混用程度 |
表格只帮助提出问题，不能替代试验。任何一项“支持”都要落到代表项目命令、预期输出和失败证据。
哪些条件优先决定选择
新建普通应用
团队没有复杂 workspace，最看重生态兼容和低培训成本时，npm 是合理默认。若安装时间和多项目磁盘占用已成为可测量问题，再评估 pnpm 或 Bun；不要为了工具新鲜度提前引入迁移成本。
多包仓库但尚未进入复杂任务图
优先比较 pnpm、Yarn Modern 与 Bun isolated 的依赖边界、workspace protocol、筛选安装和磁盘占用。若团队需要 affected、远端缓存或任务图，应另行评估 31 家族工具，不能把包管理器当成完整 Monorepo 平台。
发布公共库或插件
严格依赖可见性很重要。pnpm 严格布局、Yarn PnP 或 Bun isolated 可以暴露未声明依赖，但最终还应在 npm 风格的普通 node_modules 消费环境验证 tarball，避免只在开发仓库工作。
老旧工具链或原生依赖密集项目
先保持 npm 或 node-modules / hoisted 兼容布局，逐一审计原生安装脚本、node-gyp、Electron、移动端工具和文件监听。严格 linker 可以作为缺陷发现任务，不应和包管理器迁移在同一个变更里强行完成。
强供应链治理团队
比较的不只是 audit 命令，还包括脚本默认、源隔离、年龄门槛、lockfile 校验、插件 / patch 审批、凭证注入和缓存写权限。工具能力必须与组织流程匹配；功能存在但无人维护，等于没有控制。
最小验证与真实项目接入
最小验证不是让四个工具在空目录各装一个包，而是让一个候选工具在代表项目中完成“冻结安装、脚本执行、产物对照、冷缓存恢复、CI 双轨和回滚”闭环。下面六个阶段应写成可重复脚本和迁移记录；其中任一步失败，都保留现场而不是继续叠加配置。
迁移阶段一：建立不可争辩的现状基线
先创建迁移记录，禁止在盘点阶段生成新 lockfile：
node --version
npm --version
pnpm --version
yarn --version
bun --version
git status --short命令不存在可以记录为“未安装”，不要为了填表把四种工具都全局安装。继续检查：
git ls-files package.json package-lock.json pnpm-lock.yaml yarn.lock bun.lock bun.lockb .npmrc .yarnrc.yml pnpm-workspace.yaml bunfig.toml基线至少包含：
当前包管理器精确版本和命令来源。Node.js 版本、操作系统、CPU 架构和 shell。权威 lockfile 摘要。
registry、scope、代理和 CA 的非敏感结构。install、test、lint、build 命令与耗时。依赖树、关键 peer、原生包和安装脚本清单。
冷缓存恢复结果和产物摘要。
如果当前基线自己就不能冷恢复，应先修复现状。不能把旧工具的漂移和新工具的迁移故障混在一起。
迁移阶段二：冻结变更与定义成功标准
迁移窗口内冻结非必要依赖升级。业务代码可以继续开发，但不要让包管理器迁移 PR 同时升级框架、Node.js、构建器和 lint 规则。
成功标准应在试验前写下，例如：
所有 manifest 直接依赖不变。间接依赖变化都有转换原因和风险说明。test、lint、build 全通过，产物文件清单和关键摘要一致。
Linux CI 与 Windows / macOS 至少一个开发平台通过冷恢复。私有源、代理、CA 和最小只读凭证通过。原生依赖与 install script 行为可解释。
安装时间或磁盘收益达到预设阈值。失败时能在约定时限恢复旧工具。
没有量化成功标准，团队很容易在投入迁移成本后因为沉没成本强行上线。
迁移阶段三：转换候选，不急着删除旧事实
在独立分支安装候选工具的精确批准版本。把来源与版本写入开发镜像或工具配置；Corepack 只用于其支持的包管理器，不假设它会拦截 npm，也不用于分发 Bun。
转换 lockfile 时保留旧文件做对照，但明确它仍是当前生产基线。候选工具生成新 lockfile 后，禁止立即把旧文件删除。先审查：
直接依赖是否一一对应。Git、URL、file、workspace、patch 和 alias 是否保留语义。peer dependency 组合是否变化。
registry 来源和 integrity 是否异常。可选平台依赖是否只改变物化、不污染全局解析。overrides / resolutions / catalog 是否转换完整。
Bun 会在无 bun.lock 时自动迁移 npm、Yarn v1 或 pnpm lockfile；“自动”不代表等价已经被证明。Yarn Classic 迁入 Modern 时，配置要从 .yarnrc / .npmrc 迁入 .yarnrc.yml，且可以先保留 nodeLinker: node-modules，不要同时强推 PnP。
迁移阶段四：清除热缓存假象
候选工具第一次安装成功后，执行三轮对照：
A. 当前缓存恢复
证明基本命令和项目脚本可运行，记录耗时，但不用于最终结论。
B. 删除项目物化目录
只删除候选分支的 node_modules 或 PnP 产物，再用冻结命令恢复：
npm ci
pnpm install --frozen-lockfile
yarn install --immutable
bun ci实际只执行当前候选对应命令。这里并列是为了说明等价验证，不是要求同一目录混跑四种工具。
C. 独立冷缓存恢复
为候选工具指定全新临时缓存 / store，在与 CI 相同的网络和凭证条件下安装。预期所有包能从批准源恢复，且冻结命令不修改 manifest 和 lockfile。
冷缓存验证后检查 git status --short。任何自动改写都应视为契约不完整，而不是顺手提交。
迁移阶段五：验证脚本、生态和运行时边界
包管理器迁移最危险的结果是“安装成功，运行行为变了”。按以下顺序验证：
打印包管理器与 Node.js 精确版本。运行依赖树解释命令，检查关键包来源。运行 install script / 原生二进制专项测试。
执行 lint、typecheck、unit、integration 和 build。用原生产运行时启动最小应用。比较产物文件清单、关键摘要、source map 和包体积。
在至少两种目标平台重做冻结安装。
迁移到 Bun package manager 时，Node.js 项目应至少保留一轮明确由 node 执行的验证；迁移到 Yarn PnP 时验证 IDE SDK、ESM、测试器与 bundler；迁移到 pnpm / isolated 时重点查幽灵依赖、symlink 和文件监听。
CI 双轨对照
不要第一天就替换主分支唯一流水线。先创建候选 job，与旧 job 读取同一提交、使用相同 Node、网络和凭证，分别运行冻结安装与相同质量命令。
双轨日志至少输出：
OS / architecture
Node version
package manager version
lockfile checksum
cache key
install duration
test / build result
artifact checksum or structured diff缓存键必须包含包管理器名称、精确版本、OS / 架构和对应 lockfile 摘要。旧工具缓存不能复用为新工具缓存；否则候选 job 可能依赖历史残留而不是新契约。
双轨运行覆盖正常 PR、依赖升级 PR、私有包访问、缓存未命中和至少一次故障注入后，才考虑切换主入口。
常用操作：让证据可以复跑
团队应把盘点、冻结恢复、质量检查和产物摘要封装成不依赖具体包管理器的稳定任务名，例如 verify:deps、test、build、verify:artifact。迁移分支只替换依赖恢复入口，不重写业务验证含义。
每次试验保留四类输出：版本与环境、lockfile 摘要、依赖树关键路径、测试和产物结果。日志必须脱敏，缓存目录必须隔离。需要重跑时从干净检出开始，不在失败目录里反复删除局部文件直到“偶然成功”。
停止条件：什么时候不该继续
出现以下任一情况，应停止合入而不是靠更多兼容开关堆过去：
冻结安装仍会改写 lockfile 或 manifest。关键依赖来源、peer 组合或 patch 无法解释。必须关闭 TLS / integrity 校验才能访问源。
需要大范围 hoist 才能让未声明依赖继续工作，却没有修复计划。原生依赖在目标平台不能稳定恢复。安装脚本只能通过全局放开权限运行。
CI 冷缓存失败，只有开发机热缓存成功。产物、测试或运行结果与旧基线不一致。团队无法在约定时限恢复旧工具。
收益未达到预设阈值，却显著增加维护和培训成本。
停止不是失败，而是迁移控制发挥作用。记录证据和重试前置条件，比带着未知差异上线更有价值。
切换与回滚
切换 PR 应尽量只包含：新工具版本声明、唯一新 lockfile、必要配置、CI 命令、开发文档和旧入口删除。不要夹带业务重构。
合入前打一个可识别基线提交或标签，并保存旧 CI 日志。切换后观察安装失败率、冷缓存耗时、缓存体积、支持工单和平台差异。
回滚步骤必须预先演练：
恢复旧工具精确版本和分发入口。恢复旧 lockfile 与旧配置。删除新工具生成的物化目录和项目级临时产物。
恢复旧 CI install 命令与缓存 namespace。用旧工具执行冻结恢复。重跑 test、build 和产物对照。
撤销不再需要的 token、cache 写权限和软件分发。
回滚不能依赖从 Git 历史手工拼文件；应有一个可审查 revert 或恢复提交。
团队出现多个 lockfile
先暂停依赖变更，确认主分支权威工具和最后一次有效安装。删除非权威文件前检查是否已经携带唯一依赖变化。通过 pre-commit / CI 规则禁止多个 lockfile 共存。
本机快，CI 反而慢
本机可能命中全局 store / cache，CI 每个 job 却重新下载或错误恢复缓存。比较冷缓存、缓存 key、压缩传输时间和并发；缓存传输比重新安装更慢时，减少缓存范围而不是盲目全量上传 node_modules。
切 strict linker 后大量模块找不到
先把报错映射到具体 workspace 和 package.json。补齐真实依赖后再测试；只有确认第三方工具不支持 symlink / PnP 时才使用局部兼容配置。不要用全局 hoist 抹平所有边界。
私有包在旧工具可用、新工具 401
检查配置文件是否被候选工具读取、scope 是否正确、环境变量名称是否一致、token 是否只读且作用域匹配。不要复制用户主目录中的真实配置到仓库。
原生包只在某平台失败
比较 Node ABI、OS / CPU、libc、安装脚本执行、可选依赖和系统编译工具。lockfile 一致并不保证平台物化完全相同；把该平台加入强制迁移矩阵。
脚本名称相同但执行链不同
npm、Yarn、pnpm、Bun 对 pre/post hooks、shell、并发和依赖脚本默认可能不同。打印实际命令，拆出关键前置步骤，避免依赖隐式生命周期顺序。
选型试验必须使用最小只读 registry 凭证。包管理器迁移不应顺便改变账号体系、源服务端或 CA 信任链；一次只改变一个变量，才能定位失败。
仓库只提交：公开 registry、scope 映射、非敏感代理策略和变量占位符。真实 token、用户名密码、个人 CA 路径、内网域名和 CI 日志不得进入正文、配置示例或迁移报告。
缓存也是权限边界。能向共享 cache 写入依赖和构建产物的主体，应少于能读取缓存的主体；来自 fork 或不受信分支的任务不应覆盖主分支缓存。
包管理器只有一个 owner 不够。建议明确：
工具 owner：版本、安装来源、升级窗口与退出方案。项目 owner：代表项目、脚本、依赖图与产物确认。CI owner：冻结安装、缓存隔离、双轨 job 与日志证据。
安全 owner：registry、凭证、生命周期脚本、插件和 patch 审查。平台代表：Windows、macOS、Linux 与原生依赖验证。
团队基线至少规定唯一包管理器、唯一 lockfile、精确版本、唯一安装入口、依赖变更评审、脚本准入、缓存策略、升级节奏和回滚时限。个人偏好不能覆盖仓库契约。
包管理器版本本身是供应链依赖
只锁业务包、不锁 CLI，仍会发生 lockfile 重写和脚本语义漂移。判断标准是开发机、IDE 终端和 CI 打印出的精确版本一致，而不是文档写着“使用 pnpm / Yarn”。
磁盘模型会暴露或掩盖架构债务
从 hoisted 切到 strict linker 后出现模块缺失，通常暴露未声明依赖；从 strict 退回 hoisted 后“恢复”，不代表问题消失。团队应为兼容开关设置 owner、到期日和移除条件。
lockfile 转换无法证明语义等价
格式转换能保留大量版本和解析信息，却可能在 peer、patch、workspace、catalog、可选平台包和源映射上产生差异。必须用依赖树、冷恢复和产物对照补足证据。
速度收益可能被缓存传输和支持成本吃掉
比较总交付时间：安装、缓存上传下载、失败重试、开发支持和升级维护。只测热缓存 install，会系统性高估收益。
退出能力决定工具是否真正可治理
如果项目大量使用某工具专有协议、插件或 runtime 行为，回迁成本会持续上升。采用前列出专有能力清单，为每项标注替代方案；没有退出路径的“提效”本质上是新的平台绑定。
选型基于项目事实和决策面，不是速度排行榜或个人偏好。已记录旧工具版本、lockfile、源、缓存、脚本、测试和产物基线。迁移窗口没有同时升级 Node、框架和大批业务依赖。
新 lockfile 的版本、来源、peer、patch、workspace 与可选依赖可解释。hoisted / isolated / PnP 等磁盘模型已按目标模式验证。install script、原生扩展、私有源、代理和 CA 已进入测试矩阵。
已执行独立冷缓存恢复，冻结安装不会修改仓库文件。新旧 CI 双轨使用相同提交、环境和质量命令。停止条件量化，并在迁移前获得团队认可。
回滚可以恢复旧版本、旧 lockfile、旧缓存 namespace 和旧 CI。迁移后只保留一个包管理器入口和一个权威 lockfile。工具、项目、CI、安全和平台 owner 已明确。