📦 快速定位 >>>

一眼先记住

• corepack enable yarn pnpm：在系统里放好 / shim
• corepack use pnpm@10 packageManager：给当前项目写入 并执行安装
• corepack install：按当前项目声明的包管理器下载并安装
• corepack up：升到当前大版本线的最新版本
• corepack pack -o ./corepack.tgz：提前打离线包
• corepack install -g --cache-only ./corepack.tgz：在离线环境灌入缓存

corepack enable

cd my-project
corepack use pnpm@10
pnpm install

它解决的不是“安装依赖”，而是“统一包管理器版本”

• packageManager
• yarn.lock pnpm-lock.yaml
• 在 CI、容器、离线环境里，可以提前把包管理器本身缓存好

🚀 最小工作流 >>>

1. 启用命令入口

corepack enable

2. 给项目锁定包管理器版本

# 给当前项目写入 packageManager，并触发一次安装
corepack use pnpm@10

3. 之后直接用原生命令

pnpm install
pnpm run dev

package.json 最小示例

{
  "packageManager": "pnpm@10.32.1"
}

什么时候该再加 hash

• 团队想进一步约束供应链完整性
• 需要把版本和校验值一起固定，减少“同名版本来源不一致”的风险

{
  "packageManager": "yarn@3.2.3+sha224.953c8233f7a92884eee2de69a1b92d1f2ec1655e66d08071ba9a02fa"
}

🍳 高频场景 Recipes >>>

场景 1：给现有 pnpm 项目补上版本钉子

• 适合仓库已经在用 pnpm，但大家本地版本飘来飘去
• packageManager

corepack enable
corepack use pnpm@10
pnpm install

场景 2：仓库明明写了 pnpm，你却误敲了 yarn

• Corepack 会拦住错误的包管理器
• 这类限制正是它的价值，不建议为了省事直接关掉

# 在 packageManager 指向 pnpm 的仓库里
yarn install

# 正确做法
pnpm install

场景 3：CI / 容器里减少首次下载抖动

• 先把包管理器缓存打包到产物
• 构建节点再从本地包恢复，不依赖运行时联网

# 联网环境里先打包
corepack pack pnpm@10 -o ./.cache/corepack-pnpm10.tgz

# 离线或受限环境里恢复
corepack install -g --cache-only ./.cache/corepack-pnpm10.tgz
pnpm install --frozen-lockfile

场景 4：升级项目到同一大版本的最新发行

• pnpm@10.x
• 不想一脚跨到新 major

corepack up

场景 5：明确切到新 major 或新管理器

• up use
• use packageManager

corepack use pnpm@latest

# 或者从 Yarn 切到 pnpm
corepack use pnpm@10

⚡ 命令速查 >>>

核心命令

• corepack enable [name]：创建指定包管理器的 shim；不带参数时尽量都启用
• corepack disable [name]：移除 shim
• corepack install：下载并安装当前项目声明的包管理器
• corepack install -g pnpm@10：安装并设为系统级默认版本
• corepack use pnpm@10 packageManager：写入当前项目的 并执行安装
• corepack up：升级当前项目包管理器到同 major 最新版
• corepack pack pnpm@10 -o ./corepack.tgz：下载并打成离线档案
• corepack cache clean COREPACK_HOME：清理 缓存
• corepack pnpm@10.32.1 install：强制用某个版本执行一次命令

# 只启用 pnpm / yarn
corepack enable pnpm yarn

# 给项目拉取 packageManager 指定的版本
corepack install

# 系统外部默认走 pnpm 10
corepack install -g pnpm@10

# 排查回归时用指定版本跑一次
corepack pnpm@10.32.1 install

use、install、up 怎么选

• corepack use ...：改项目声明，适合初始化或显式升级
• corepack install：不改声明，只把当前项目需要的版本装下来
• corepack up：只在当前 major 线上追最新

enable 和 install -g 的差别

• enable
• install -g
• enable use install

🧾 项目声明速查 >>>

packageManager

• 必须是明确版本，不能只写名字
• yarn npm pnpm
• 可以附加 hash
• .js .tgz

{
  "packageManager": "pnpm@10.32.1"
}

devEngines.packageManager

• 用来校验开发环境是否匹配
• onFail: ignore | warn | error
• packageManager

{
  "devEngines": {
    "packageManager": {
      "name": "pnpm",
      "version": "10.32.1",
      "onFail": "error"
    }
  }
}

🌐 离线、代理与缓存 >>>

最小离线流程

# 在能联网的机器上准备档案
corepack pack yarn@stable -o ./corepack-yarn.tgz

# 在目标机器上仅从离线档案安装缓存
corepack install -g --cache-only ./corepack-yarn.tgz

常见环境变量

• COREPACK_HOME：Corepack 缓存目录
• COREPACK_ENABLE_NETWORK=0：禁止联网，要求你自己预热缓存
• COREPACK_DEFAULT_TO_LATEST=0：不再自动查远端最新版本
• COREPACK_ENABLE_AUTO_PIN=1 packageManager：发现项目没写 时自动补写
• COREPACK_NPM_REGISTRY：指定拉包管理器时使用的 registry
• HTTP_PROXY HTTPS_PROXY NO_PROXY：代理设置

# 受限环境里显式关闭网络
$env:COREPACK_ENABLE_NETWORK="0"
corepack install

🪟 Windows / Node 版本分支 >>>

Node 版本要点

• 14.19.0 <25.0.0
• 25.0.0
• corepack@0.34.6 engines ^20.10.0 || ^22.11.0 || >=24.0.0

Windows 常见处理

• .msi
• PowerShell 下如果二进制所在目录不可写，可以用函数别名兜底

function pnpm { corepack pnpm @args }
function yarn { corepack yarn @args }
function npm { corepack npm @args }

🛠️ 排障速记 >>>

高频症状与处理

• pnpm yarn corepack enable：先跑
• 仓库里写的是 pnpm，却被拒绝执行 yarn : 不是 bug，说明项目声明生效
• pack：检查代理、registry、DNS，再考虑先
• DEBUG=corepack
• corepack cache clean

# Linux / macOS
DEBUG=corepack corepack install

# PowerShell
$env:DEBUG="corepack"
corepack install

# 清缓存后重装
corepack cache clean
corepack install

Quick Ref

• corepack use
• corepack install
• corepack up
• corepack pack corepack install -g --cache-only
• corepack enable