# Pnpm Major Migrator

> 迁移 pnpm 大版本（major）及其项目配置时使用。适用于用户提到 upgrade pnpm major、pnpm v10 to v11、pnpm migration、迁移 pnpm 版本、lockfile 升级、pnpm-workspace.yaml 迁移、.npmrc 配置迁移、GitHub Actions pnpm 版本对齐。当前优先覆盖 v10 到 v11，并保留后续 v12+ 的可扩展流程。

- Skill: `caomeiyouren/pnpm-major-migrator` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add caomeiyouren/pnpm-major-migrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/caomeiyouren/pnpm-major-migrator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: caomeiyouren (https://skillmd.com/u/caomeiyouren)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/caomeiyouren/pnpm-major-migrator

---


# Pnpm Major Migrator

铁律：不要在未完成基线采集、回滚预案和最小质量门之前直接升级 pnpm major。

## 工作流

- [ ] Step 1: 做迁移基线与目标确认 ⚠️ REQUIRED
  - [ ] 1.1 确认当前 pnpm 版本、目标版本、Node 版本范围和 CI 运行环境。
  - [ ] 1.2 盘点仓库中的 pnpm 相关配置入口：`package.json`、`pnpm-lock.yaml`、`pnpm-workspace.yaml`、`.npmrc`、`.github/workflows/*`、`Dockerfile*`。
  - [ ] 1.3 记录并锁定当前可用质量门命令（lint/test/build/typecheck）。
- [ ] Step 2: 判断迁移画像（Migration Profile） ⚠️ REQUIRED
  - [ ] 2.1 根据当前 major 与目标 major，选择对应迁移画像。
  - [ ] 2.2 如果是 `v10 -> v11`，必须执行 references/v10-to-v11-checklist.md 的专项清单。
  - [ ] 2.3 如果是其他版本，先使用 references/version-profiles.md 的通用框架，再补充目标版本 changelog 差异。
- [ ] Step 3: 执行自动化迁移
  - [ ] 3.1 在仓库根目录运行官方 codemod（如适用）：`pnpx codemod run pnpm-v10-to-v11`。
  - [ ] 3.2 将机械化改动集中处理：配置字段迁移、键名重命名、lockfile 重生成，并在“原先已存在 `packageManager` 字段”时才对齐该字段。
  - [ ] 3.3 对 CI 里的 pnpm 版本策略做显式化，仅固定 major（例如 `10`、`11`），不固定 minor/patch，且避免 `latest` 漂移。
  - [ ] 3.4 若项目使用 `Dockerfile`/`Dockerfile.*` 构建，统一更新镜像内 pnpm 安装与缓存配置，保证与仓库目标 major 一致。
- [ ] Step 4: 处理人工确认项 ⚠️ REQUIRED
  - [ ] 4.1 审核 codemod 无法覆盖的项（例如 CVE -> GHSA 映射、环境变量前缀迁移）。
  - [ ] 4.2 审核脚本名与 pnpm 内置命令冲突风险（如 clean/setup/deploy/rebuild）。
  - [ ] 4.3 审核破坏性行为变化（例如 link/server/全局安装语义变化）对现有流程的影响。
- [ ] Step 5: 验证与回滚保障 ⚠️ REQUIRED
  - [ ] 5.1 先验证依赖安装是否成功（无异常退出、无缺失依赖、工作区安装完整），再运行最小充分质量门；涉及 CI/锁文件/配置迁移时升级为完整质量门。
  - [ ] 5.2 校验 `pnpm-lock.yaml` 是否按预期更新，并确认未引入新的报错/告警（含 `ERR_PNPM_IGNORED_BUILDS`、脚本执行失败、类型错误、lint/test 回归）。
  - [ ] 5.3 人工复查 `pnpm-workspace.yaml` 中 `allowBuilds` 每个 key 的 value 是否为合法的 boolean（`true`/`false`），而非占位符字符串。发现占位符立即修正。
  - [ ] 5.3 若出现新问题，先修复再交付；修复后重复执行安装与质量门，直到通过或形成明确阻塞说明。
  - [ ] 5.4 输出迁移报告：变更文件、人工遗留项、风险等级、回滚方式。
  - [ ] 5.5 若质量门失败且短期不可修复，优先回退到最近稳定提交并拆分批次重试。

## 当前优先画像：v10 到 v11

- 必须使用 references/v10-to-v11-checklist.md。
- 重点检查以下高风险面：
  - `package.json#pnpm` 是否已迁移到 `pnpm-workspace.yaml`。
  - `.npmrc` 中非 auth/registry 配置是否已迁移到 `pnpm-workspace.yaml`。
  - 构建依赖相关配置是否统一到 `allowBuilds` 语义。**关键规则**：
    - v11 要求 `allowBuilds` 和 `onlyBuiltDependencies` **必须配对出现**，单独存在任何一个都无效。两者都缺失会拦截所有构建脚本。
    - 正确写法示例：
      ```yaml
      allowBuilds:
        esbuild: true
      onlyBuiltDependencies:
        - esbuild
      ```
    - 配置位置在 `pnpm-workspace.yaml`（非 workspace 项目也适用）。
  - 确认 `pnpm-workspace.yaml` 中的 `allowBuilds` 覆盖了所有需要构建脚本的依赖（如 esbuild、sharp、workerd 等），否则 `pnpm install` 会报 `ERR_PNPM_IGNORED_BUILDS`，导致本地与 CI 均无法构建。
  - ⚠️ **校验 `allowBuilds` 值均为合法 boolean**：`allowBuilds` 下的 value **必须是 `true` 或 `false`**，不能是字符串占位符（如 `"set this to true or false"`）。占位符文本在 YAML 语法上合法（被解析为字符串），但 pnpm 不会将其解释为允许构建，`pnpm install` 仍会报错。
  - 旧 strictness 配置是否迁移到 `pmOnFail`。
  - `auditConfig.ignoreCves` 是否改为 `auditConfig.ignoreGhsas`，并补做 CVE 到 GHSA 的人工映射。

## 后续版本扩展位

- 迁移画像扩展：在 references/version-profiles.md 增加 `v11 -> v12`、`v12 -> v13` 专项节。
- 规则扩展：将新版本破坏性变更按“自动化可处理/需人工确认/需业务决策”三类归档。
- 验证扩展：为常见 CI 平台（GitHub Actions、Docker、Cloudflare）补充最小验证矩阵。

## 反模式

- 只升级 `packageManager` 字段，不同步 lockfile 与 CI。
- 在原本没有 `packageManager` 的项目里强行新增该字段。
- 未清点 `.npmrc` 与 `pnpm-workspace.yaml` 的职责边界，导致配置失效。
- 更新了 workspace/CI 配置但遗漏 `Dockerfile`，导致容器构建与本地环境版本漂移。
- 未记录人工遗留项就宣告迁移完成。
- 在 `latest` 模式下跑迁移并提交，造成后续不可复现。
- 迁移后未确认 `allowBuilds` 配置是否覆盖关键构建依赖，导致 CI 中出现 `ERR_PNPM_IGNORED_BUILDS`。
- `allowBuilds` 的 value 残留占位符文本（如 `"set this to true or false"`），在 YAML 语法上合法但 pnpm 无法识别，等同于未配置。
- 使用 `-replace` 或字符串操作修改 YAML 文件（如 `pnpm-workspace.yaml`）时，缩进错误会导致整个文件解析失败。修改 YAML 的正确做法：先 `Get-Content -Raw` 读全文件检查 key 是否已存在，插入时确保缩进与已有条目对齐（2 空格）；或用 Write 工具全量覆写。

## 交付前检查

- [ ] 已明确当前版本、目标版本和迁移画像。
- [ ] 已执行对应版本专项清单（v10 -> v11）或通用画像清单（其他版本）。
- [ ] 已完成安装成功性检查、lockfile 更新检查与质量门验证，并修复新增问题或给出阻塞说明。
- [ ] 已人工复查 `allowBuilds` 的所有 value 是否为 `true`/`false`，无占位符字符串残留。
- [ ] CI 中 pnpm 版本策略已显式可复现，且仅固定 major。
- [ ] 若项目使用 Docker 构建，容器内 pnpm 版本策略已同步到目标 major。