pnpm-lock.yaml在Monorepo中的作用及npm转pnpm迁移问题咨询

核心问题拆解与处理步骤 #

1. 解决 legacy-peer-deps 无效的问题 #

pnpm 对对等依赖的处理逻辑与 npm 存在差异，即便 .npmrc 中配置了 legacy-peer-deps=true，仍可能因严格的依赖校验触发报错。可通过以下方式调整：

• 确认 pnpm 版本：使用 pnpm 7.x 及以上版本，该版本对 legacy-peer-deps 的支持更完善。
• 补充对等依赖规则：在根目录的 pnpm-workspace.yaml 中添加 peerDependencyRules，针对性放宽冲突限制，示例：

  peerDependencyRules:
    # 忽略缺失的对等依赖
    ignoreMissing:
      - react
      - react-dom
    # 允许任意版本的冲突依赖
    allowAny:
      - [你的冲突依赖包名]
  

• 保留现有 .npmrc 配置：auto-install-peers=true 配合 legacy-peer-deps=true 可确保对等依赖自动安装，同时忽略版本冲突。

2. 确保根目录 pnpm-lock.yaml 为唯一锁文件 #

Bazel 集成要求使用根目录锁文件，需保证其包含所有工作区的依赖解析结果：

• 清理子目录锁文件：删除所有子项目（ui/web、shared-ui、e2e）下的 package-lock.json 和 pnpm-lock.yaml，避免干扰。
• 重新生成根锁文件：在项目根目录执行 pnpm install，pnpm 会扫描 pnpm-workspace.yaml 中声明的所有工作区，生成包含完整依赖树的根目录 pnpm-lock.yaml。

3. pnpm install --filter 的依赖优先级 #

执行 pnpm install --filter main-project e2e 时：

• 优先读取根目录的 pnpm-lock.yaml，只要锁文件中已记录目标项目的依赖解析结果，pnpm 会直接按锁文件安装。
• 若要强制完全依赖根锁文件（禁止因 package.json 变更更新锁文件），添加 --frozen-lockfile 参数：

  pnpm install --filter main-project e2e --frozen-lockfile
  

• 只有当目标项目的 package.json 存在未被锁文件记录的依赖变更时，pnpm 才会更新锁文件对应部分后执行安装。

内容的提问来源于stack exchange，提问作者Mithun Shreevatsa