pnpm 替换 npm：迁移步骤与常见坑

把项目从 npm 迁到 pnpm，真正要确认的不是“命令怎么敲”，而是 lockfile、依赖布局、CI 和团队协作习惯会不会一起变。大多数前端项目迁移都不复杂，但最常见的坑也很固定：旧锁文件没清理、CI 还在跑 npm、某些包依赖扁平结构，以及把 shamefully-hoist 当默认选项。

目录

• 什么时候值得迁移到 pnpm
• 迁移前先确认三件事
• 安装 pnpm
• 一个最稳的迁移顺序
  • 1. 删除 npm 旧产物
  • 2. 重新安装
  • 3. 把脚本调用切过来
• CI 里最容易漏的点
• shamefully-hoist 什么时候才该开
• 常见问题
  • 安装卡住或异常慢
  • lockfile 频繁变化
  • 某些包找不到依赖
• 和 npm、yarn 对比时别混成一件事
• 结论
• 参考资料

什么时候值得迁移到 pnpm

如果你的项目出现这些情况，迁移通常有明显收益：

• 多项目或 monorepo，依赖重复安装明显
• node_modules 占空间大、装依赖慢
• 想要更严格地暴露依赖声明问题

pnpm 官方文档说明 pnpm install 会安装项目依赖，并在 workspace 中默认递归安装所有项目。它的关键特点之一就是共享 store 和更严格的依赖链接。

迁移前先确认三件事

1. 团队和 CI 都能统一使用 pnpm。
2. 仓库里没有必须依赖 npm 扁平结构的老包。
3. 你愿意把 package-lock.json 切换成 pnpm-lock.yaml。

如果只是你本机临时想试一下，而团队其余流程仍然是 npm，这不叫真正迁移。

安装 pnpm

macOS：

brew install pnpm

或者已有其他方式管理 Node 环境时，也可以按团队统一方案安装。

一个最稳的迁移顺序

1. 删除 npm 旧产物

rm -rf node_modules package-lock.json

2. 重新安装

pnpm install

pnpm 官方文档说明，pnpm install 会生成或更新 pnpm-lock.yaml，并在 CI 中默认更严格地处理 lockfile 一致性。

3. 把脚本调用切过来

原来：

npm run dev
npm run build

迁移后：

pnpm dev
pnpm build

大多数脚本本身不用改，调用方式和 lockfile 才是关键变化。

CI 里最容易漏的点

如果仓库已经提交了 pnpm-lock.yaml，CI 就不应该继续跑 npm install。pnpm 官方文档写得很明确：CI 环境里如果 lockfile 存在但需要更新，安装会失败；--frozen-lockfile 在 CI 里也默认更严格。

这意味着：

• 本地和 CI 必须用同一种包管理器
• lockfile 要跟代码一起评审
• 不要一边提交 pnpm-lock.yaml，一边让流水线继续跑 npm

shamefully-hoist 什么时候才该开

pnpm 官方文档把 --shamefully-hoist 描述为创建类似 npm / yarn 的扁平 node_modules 结构，并明确标注为“highly discouraged”。

也就是说：

• 它是兼容开关，不是推荐默认值
• 只有当你确认某些历史依赖确实要求扁平结构时再开
• 最好先定位具体包，再决定是否局部或暂时妥协

如果一迁移就直接打开它，你就把 pnpm 很多约束价值抵消掉了。

常见问题

安装卡住或异常慢

先看网络、registry、磁盘空间，再考虑缓存：

pnpm store prune
df -h

lockfile 频繁变化

先确认团队 pnpm 版本是否一致，再看是否有人混用 npm / yarn。

某些包找不到依赖

这通常不是 pnpm “坏了”，而是包本身依赖声明不规范，过去只是被 npm 的扁平结构掩盖了。

和 npm、yarn 对比时别混成一件事

这篇是迁移指南，不是三者全面对比。如果你是在评估工具选择而不是执行迁移，更适合看 pnpm vs npm vs yarn 对比。

结论

• 迁移核心不是改命令，而是统一 lockfile、CI 和团队习惯。
• pnpm install 后要让 pnpm-lock.yaml 成为唯一锁文件来源。
• shamefully-hoist 只能当兼容兜底，不该作为默认配置。

参考资料

• pnpm install