pnpm 11 升级变化扫盲：变化清单 + 避坑指南

下班之后没人亲亲，敲段代码哄自己开心。写个demo修完bug，誓让女神喊你哥哥。

pnpm 11 不是功能堆料，而是一次“地基重铺”——安全默认项被固化，配置体系大挪移。升级的痛感不在新功能，在配置搬家。

一、版本主要变化

1. Node 22 成硬门槛

不再支持 Node 18 / 19 / 20 / 21，要求 Node.js 22+；
pnpm 自身改为纯 ESM 分发；
独立可执行文件要求 glibc 2.27+（老 Linux 注意）。

2. 供应链保护默认开启（v10 还是“建议开”，v11 直接出厂默认）

minimumReleaseAge 默认 1 天（1440 分钟）：刚发布不满 1 天的包默认装不到；
blockExoticSubdeps 默认 true：默认拦截非标准来源的子依赖（如直接 git/curl 拉取的依赖）。
关闭方式：在 pnpm-workspace.yaml 设 minimumReleaseAge: 0（不建议）。

3. 存储索引换 SQLite（store v11）

旧版“每包一个 JSON 索引” → 单个 SQLite 数据库，打包 manifest 与十六进制摘要；
收益：安装更快、文件系统调用更少（大仓库 / CI 频繁安装体感明显）。

4. 全局安装隔离

pnpm add -g 默认走隔离的全局虚拟存储，每次安装自带 package.json / node_modules / lockfile，互不干扰；
关闭：enableGlobalVirtualStore: false。

5. 发布流程“去 npm CLI 化”

publish / login / logout / view / deprecate / unpublish / dist-tag / version 改为 pnpm 原生实现，不再委托 npm CLI；
.npmrc 从此只管认证 + 注册源。

二、重大配置变更

① .npmrc 被“瘦身”——只留认证和 registry 其余所有配置必须搬到 pnpm-workspace.yaml 或全局 ~/.config/pnpm/config.yaml。网络类设置（httpProxy / httpsProxy / noProxy / localAddress / strictSsl / gitShallowHosts）也在搬家之列。

② allowBuilds 取代 5 个旧配置（已移除）

移除项：onlyBuiltDependencies、onlyBuiltDependenciesFile、neverBuiltDependencies、ignoredBuiltDependencies、ignoreDepScripts
新写法——一个“包名 → 是否允许跑构建脚本”的映射：

# pnpm-workspace.yaml
allowBuilds:
  esbuild: true
  "@swc/core": true
  "github:some/package": false

③ 环境变量前缀 pnpm_* → pnpm_config_*

# 旧
pnpm_onlyBuiltDependencies=esbuild
# 新
pnpm_config_onlyBuiltDependencies=esbuild

④ pnpm audit 过滤：CVE → GHSA

# 旧
auditConfig:
  ignoreCves: ["CVE-2024-xxxx"]
# 新
auditConfig:
  ignoreGhsas: ["GHSA-xxxx-xxxx-xxxx"]

（顺带：audit --fix=update 可在 lockfile 直接升级修复，--fix --interactive 可交互选择。）

⑤ Patch 相关硬改动

allowNonAppliedPatches 移除，改用 allowUnusedPatches；
ignorePatchFailures 移除：patch 应用失败现在直接抛错。
影响：仓库里那些“其实没生效却被静默忽略”的补丁，升级后会第一次暴露。

⑥ node-mirror:（.npmrc）→ nodeDownloadMirrors（workspace.yaml）

# pnpm-workspace.yaml
nodeDownloadMirrors:
  release: https://my-mirror.example.com/download/release/

三、对开发者的实质影响

CI / 本地必须先升 Node 22：这是前置条件，否则装完 pnpm 直接跑不起来。
codemod 只管机械迁移，三类得手补：.npmrc 搬家、allowBuilds 重写、ignoreGhsas 改写。
升级后跑 pnpm setup：让新的 bin 子目录进 PATH，否则命令可能指向错位置。
构建白名单会失效：不重写 allowBuilds，依赖里的原生 postinstall 会被全部拦截，装出来的 node_modules 可能跑不起来。
新包要等 1 天：等某个刚发的 hotfix 时，默认装不到，要么等要么临时 minimumReleaseAge: 0。
全局工具隔离是双刃剑：全局 CLI 环境更“重”，假定“全局共享 node_modules”的老脚本可能失效。

四、升级步骤

升 Node 到 22+（CI / 本地 / 镜像同步）
跑 pnpm-v10-to-v11 codemod 做机械迁移
手动补三类配置：.npmrc 搬家 → allowBuilds 重写 → ignoreGhsas 改写
pnpm setup 刷新 PATH
pnpm install 验证：确认没有 postinstall 被静默拦截、没有 patch 静默失败

团队层面：把 Node 22 + 标准 pnpm-workspace.yaml 写进脚手架模板，让新项目天生合规。

结语：这次升级到底改了什么

把上面的变动收拢成一句话结论——pnpm 11 的升级，本质是三件事：抬门槛、搬配置、固安全。

抬门槛：Node 22 成硬性要求，pnpm 自己转纯 ESM。这是前置条件，不满足直接跑不起来。
搬配置：.npmrc 退居“只管认证/registry”，其余设置全部迁到 pnpm-workspace.yaml / 全局 config.yaml；allowBuilds 一口气取代 5 个旧构建白名单配置；环境变量、audit 过滤、node 镜像的写法统统换前缀或换字段。
固安全：供应链保护出厂默认开启（新包 1 天内装不到、非标子依赖默认拦截），存储换 SQLite 提速，全局安装隔离互不干扰。

变动看着多，但绝大多数配置改动是机械的、可脚本化的。把它想清楚，升级就顺了。