Corepack 工程手册：包管理器版本契约与离线交付
命令入口与项目版本契约为何会失配
Corepack 解决的不是“项目依赖应该装哪个版本”，而是“执行 yarn 或 pnpm 时究竟启动哪个包管理器版本”。没有这层契约时，开发机全局 Yarn、CI 镜像里的 pnpm 和仓库 lockfile 各自演进，同一个提交会被不同工具解释。Corepack 在命令入口与真实包管理器之间放置 shim，根据项目 package.json 的 packageManager 选择、下载、校验、缓存并执行目标版本。
故障定位必须先把四层对象拆开：Shell 命中的 shim、Corepack 自身版本、packageManager 声明的 Yarn 或 pnpm 版本，以及 lockfile 固定的项目依赖。Corepack 只管理前三者之间的入口契约，不解释 Yarn、pnpm 或 npm 的依赖图，也不替代依赖缓存服务、SBOM 或供应链扫描器。
当报错已经进入 lockfile 解析、workspace、生命周期脚本或项目依赖 registry，应转到对应包管理器排查；当问题发生在 yarn / pnpm 命令指向错误版本、离线环境缺少包管理器 archive、签名校验失败或 CI 与本地入口不一致时，Corepack 才是主诊断对象。
先确认 shim 由谁创建
准备一台具备项目批准版 Node.js 和 npm 的 Windows、macOS 或 Linux 开发机：
node --version
npm --version先纠正两个高风险假设，并在目标环境用 Node.js Corepack 仓库 的安装与兼容说明复核：
Corepack 仍是实验性能力，不能当成 Node.js 永久稳定接口。官方 Corepack 仓库明确：它曾随 Node.js 14.19.0 至 25.0.0 之前的版本分发，Node 25 起不再随 Node 分发。升级 Node 后 corepack 消失是分发边界变化，不一定是 PATH 损坏。
因此，团队必须把 Corepack 自身也当作需要版本、来源、升级和退出策略的工具。不能只在 onboarding 文档写一句 corepack enable，然后假设所有 Node 镜像永远具备相同命令。
Corepack 在命令链中的位置
以执行 yarn install 为例，真实链路是：
Shell 解析 yarn
-> Corepack 创建的 yarn shim
-> 向上查找 package.json
-> 读取 packageManager / devEngines.packageManager
-> 查本地 Corepack 缓存
-> 必要时从 registry 下载并校验包管理器
-> 启动精确版本 Yarn
-> Yarn 读取 yarn.lock 并安装项目依赖这里有三种不同的“版本”：Node.js 版本决定运行 Corepack 的运行时；Corepack 版本决定 shim、下载与校验逻辑；packageManager 决定最终 Yarn 或 pnpm 版本。项目依赖版本则由 yarn.lock、pnpm-lock.yaml 或其他 lockfile 决定。把这四层混成“Node 环境”会让升级故障无法定位。
Corepack 不会替 Yarn 解释 yarn.lock，也不会替 pnpm 管理 store。它只负责把正确的包管理器进程交给项目。执行到了 Yarn/pnpm 后的解析、缓存、脚本和 registry 凭证仍由该包管理器处理。
安装与启用入口
先检查：
corepack --version如果命令存在，仍要记录它来自 Node 分发还是独立 npm 安装。Windows PowerShell 可用：
Get-Command corepack -All
Get-Command yarn -All
Get-Command pnpm -AllPOSIX Shell 可用：
command -v corepack
command -v yarn
command -v pnpmNode 25 及后续环境，或组织决定独立治理 Corepack 时，按官方仓库入口安装：
npm install --global corepack
corepack --version不要把 corepack@latest 写成企业基线。个人验证可以跟随官方最新版本，团队镜像应在升级评审后安装批准的精确版本，并记录 npm 包来源与完整性证据。
若机器以前全局安装过 Yarn 或 pnpm，它们可能抢占命令名。先识别来源；确认没有其他项目依赖后，才按官方建议移除旧全局二进制：
npm uninstall --global yarn pnpm
corepack enablecorepack enable 会在 Corepack 安装位置附近创建包管理器 shim。它需要对目标目录有写权限；受管开发机、只读 Node 目录和某些容器镜像中可能失败。不要立刻提升到长期管理员终端，先使用 --install-directory 选择受控目录，并把该目录加入 PATH：
corepack enable --install-directory <approved-bin-directory>Windows 通过 Node .msi 安装的 Corepack 还存在 MSI feature 边界。若要用 npm 安装的 Corepack 替换它，官方仓库建议先在应用修改界面移除安装器中的 Corepack Manager feature，避免 Windows Installer 维护的文件与 npm 全局文件互相覆盖。
启用后验证的重点不是“出现版本号”，而是命令确实经过预期 shim：
corepack --version
yarn --version
pnpm --version首次调用可能访问网络获取 Known Good Release，因此无项目目录下的结果不能作为团队版本证据。下一节必须建立项目契约。
用 packageManager 固定项目入口
创建最小实验：
mkdir corepack-lab
cd corepack-lab
npm init --yes
corepack use yarn@stablecorepack use 会解析稳定通道、写入 package.json#packageManager，并执行安装。随后检查：
node -p "require('./package.json').packageManager"
yarn --version预期 packageManager 类似：
{
"packageManager": "yarn@<精确版本>"
}这里的 <精确版本> 只是说明，实际文件必须由命令写入真实值。yarn --version 应与其一致。stable 只用于首次选择，解析完成后仓库中不得继续保存浮动标签。
再创建 verify.cjs：
console.log("corepack-ok");给 package.json 增加脚本：
{
"scripts": {
"verify": "node verify.cjs"
}
}执行：
yarn install --immutable
yarn verify预期输出：
corepack-ok这个实验同时验证了 shim 能找到项目、Corepack 能解析并启动精确 Yarn、Yarn 能读取项目和执行脚本。若只运行 corepack --version，只能证明 Corepack CLI 存在，不能证明项目版本契约生效。
提交时应包含 package.json、目标包管理器 lockfile 和项目需要的配置。CI 先打印：
node --version
corepack --version
yarn --version
node -p "require('./package.json').packageManager"四条输出使故障能够归属到 Node、Corepack、包管理器选择或项目依赖层。
packageManager 与 devEngines.packageManager
packageManager 是最直接的项目契约，格式包含受支持的包管理器名称和版本，官方还支持带 hash 的形式。团队应优先让 Corepack 命令写入它，而不是手工拼接未知 hash。
Corepack 还支持 devEngines.packageManager，可表达名称、版本与不匹配处理策略。它适合在组织模板中对开发工具做额外约束，但不能和 packageManager 写出互相冲突的版本。采用前应先在目标 Corepack 版本验证字段行为，并确保旧 Corepack 或其他工具不会忽略关键策略。
架构上应坚持一个事实源：通常以 packageManager 为执行选择，CI 额外检查它是否满足组织策略。不要同时依赖全局默认、packageManager、自定义 Shell wrapper 和 CI 镜像硬编码四套版本；多套入口只会让本地与流水线各自“都正确”。
Known Good Release 不是项目锁定
当当前目录及父目录没有 packageManager 时，Corepack 会使用 Known Good Release。若本地没有对应记录，它可能查询 registry 并缓存版本；官方仓库还说明，同一 major 线的下载可能更新 Known Good Release。
这适合在空目录中提供可用默认值，却不适合作为受审查项目的版本策略。今天和下周的新开发机可能得到不同默认版本，且网络策略会影响首次解析。
若组织希望在无项目上下文中也保持受控默认，可显式安装：
corepack install --global yarn@<approved-version>
corepack install --global pnpm@<approved-version>项目内仍以 packageManager 优先。可以设置：
COREPACK_DEFAULT_TO_LATEST=0来阻止 Corepack 查询最新默认值和自动更新同 major 的 Known Good Release，但环境变量不是仓库锁定的替代品。它更适合作为受控镜像的网络与漂移防线。
离线环境先预热包管理器
离线构建常见误区是只缓存项目依赖，却忘了 Corepack 首次还需要获取 Yarn/pnpm 本体。结果是 registry 依赖归档齐全，构建仍在第一条 yarn 命令前失败。
在线准备机进入已经固定 packageManager 的项目，生成 Corepack archive：
corepack pack -o corepack.tgz把 archive 当作构建输入进行校验、扫描和受控制品传递。离线环境安装到 Corepack cache：
corepack install --global --cache-only ./corepack.tgz然后禁止网络并验证：
COREPACK_ENABLE_NETWORK=0 yarn --version
COREPACK_ENABLE_NETWORK=0 yarn install --immutableWindows PowerShell 可用：
$env:COREPACK_ENABLE_NETWORK = "0"
yarn --version
yarn install --immutable第一条只证明包管理器 binary 已预热；第二条还要求 Yarn 自己的依赖缓存或私有镜像可用。Corepack archive 和 Yarn cache 是两层不同资产，必须分别验收。
容器镜像可在有网络的 build stage 运行 corepack pack 或预装批准版本，再把必要 cache 带入离线 stage。不要把用户主目录下整个 Corepack cache 无筛选复制进镜像；它可能包含未使用版本、旧签名数据和不必要体积。
缓存位置、清理与重置
官方仓库说明，默认 COREPACK_HOME 在 Windows 通常位于 %LOCALAPPDATA%\node\corepack，其他平台通常位于 $HOME/.cache/node/corepack。团队脚本不应假定固定路径，而应通过环境与实际工具版本确认。
查看当前环境：
corepack --version需要清理 Corepack 管理的包管理器版本时使用官方命令：
corepack cache clean清理前记录失败版本、缓存路径和复现日志。缓存损坏的修复流程应是：确认目标项目版本 -> 清理 Corepack cache -> 在可信网络重新预热 -> 关闭网络再执行版本验证。删除 cache 不会修改项目 packageManager，也不应删除 Yarn/pnpm lockfile。
撤销 shim：
corepack disable若启用时使用了自定义目录，禁用时也要指向相同目录。disable 只是移除 shim，不会自动删除 npm 全局 Corepack、项目字段或所有缓存。完整卸载要按来源执行：npm 安装用 npm uninstall --global corepack，Node MSI feature 用系统修改入口。卸载前要确认其他仓库已有替代入口。
代理、CA 与 registry 凭证
Corepack 下载的是包管理器本体，它的网络配置与 Yarn/pnpm 下载项目依赖的配置不是同一层。官方仓库说明，Corepack 可通过 NODE_USE_ENV_PROXY=1 使用 HTTP_PROXY、HTTPS_PROXY 和 NO_PROXY：
NODE_USE_ENV_PROXY=1 HTTPS_PROXY=http://proxy.example.invalid:8080 corepack install示例地址不可直接使用。企业环境应通过受控环境注入代理，并确认 NO_PROXY 包含内部 registry 的准确边界。若 TLS 被企业代理重新签发，应把组织 CA 安装进 Node.js 能识别的信任链；不要关闭 TLS 校验或绕过完整性检查。
当 Corepack 本体托管在 npm 类型 registry 时，可使用 COREPACK_NPM_REGISTRY 指定基地址，并通过 COREPACK_NPM_TOKEN 或用户名/密码环境变量认证。真实凭证只能进入 Secret 管理系统和进程环境，不能写进 package.json、镜像层、命令历史或 CI 调试输出。
Corepack 的 registry 认证只保护“获取包管理器”这一步。Yarn 的 npmScopes、pnpm 的 registry 与项目依赖 token 仍需各自配置。不要为了省事把一个可发布、可管理账户的长效 token 同时给 Corepack、依赖安装和包发布。
完整性与签名失败不能靠跳过
Corepack 在下载包管理器时会执行完整性检查。官方提供 COREPACK_INTEGRITY_KEYS 等高级入口，也允许用特殊值跳过检查；企业基线不应把“跳过”作为签名轮换或旧客户端失败的常规修复。
出现 signature 或 integrity 错误时按以下顺序处理：
记录 Node、Corepack、目标包管理器版本和下载 registry。检查系统时间、代理是否篡改响应、镜像是否同步完整。在隔离环境用官方 registry 与批准的新版 Corepack复现。
对照 Corepack release / repository 检查密钥轮换和兼容说明。更新 Corepack 或修复镜像元数据，再重新预热 cache。
临时关闭完整性检查会让任意被代理、镜像或网络替换的包管理器以开发者权限执行。即使只为“救一次构建”，它也改变了整个依赖安装控制面，必须按安全例外处理，而不是复制到 Dockerfile 和全局环境。
CI 等价入口
一个最小 CI Job 应显式准备 Corepack，而不是依赖 runner 恰好自带：
npm install --global corepack@<approved-corepack-version>
corepack enable
node --version
corepack --version
yarn --version
yarn install --immutable
yarn verify其中 <approved-corepack-version> 必须由流水线变量、基础镜像或仓库工具清单提供真实精确值，不能原样执行。Node 25 后这一安装步骤尤其不能省略。若基础镜像已经固定 Corepack，Job 可以只验证版本，但镜像构建记录必须可追溯到同一批准值。
本地与 CI 的等价性不是复制所有机器状态，而是共享以下契约：
同一 Node 主线和平台支持矩阵。同一精确 Corepack 版本或经过验证的兼容范围。同一 packageManager 字段与包管理器版本。
同一不可变安装和项目脚本入口。同一私有源信任边界，凭证按环境分别注入。
CI 不应通过 COREPACK_ENABLE_STRICT=0 或 COREPACK_ENABLE_PROJECT_SPEC=0 绕过仓库声明。确有迁移期兼容需求时，必须限定 Job、记录期限，并保留一个严格 Job 证明目标状态。
从现象回到原因
升级 Node 后找不到 corepack
旧镜像能执行 corepack enable，新 Node 镜像提示命令不存在。 记录 node --version，检查镜像清单和 Get-Command corepack / command -v corepack。 Node 25 起不再随 Node 分发 Corepack，或发行版安装包裁剪了相关组件。 按批准精确版本独立安装 Corepack，并在镜像构建阶段启用 shim。 全新容器中打印 Node/Corepack/Yarn 三层版本并完成不可变安装。
corepack enable 权限不足
报 EACCES、EPERM 或无法写入 Node 安装目录。 定位 Corepack 与 Node 路径，检查目标目录所有者和是否只读。 shim 默认写到 Corepack 邻近目录，系统安装或只读镜像不允许普通用户修改。 在镜像构建时写入，或用 --install-directory 指向受控用户 bin；避免长期管理员 Shell。 新终端解析到该目录下的 shim，普通用户可执行项目命令。
packageManager 与实际 Yarn 不一致
packageManager 固定 Yarn 4，但输出是 Yarn 1 或另一版本。 查看所有 yarn 路径，检查 shim 是否启用、当前目录是否位于项目根下。 全局 Yarn 抢占 PATH、Shell 命令缓存、从错误目录执行，或 Corepack strict 策略被关闭。 移除冲突全局入口，重建 shim，恢复严格项目检查并重开 Shell。 项目根和子目录中的 yarn --version 都与字段一致，仓库外默认值不影响项目。
离线环境仍尝试联网
已经带入项目依赖缓存，但第一条 yarn 命令访问 registry。 设置 COREPACK_ENABLE_NETWORK=0，区分失败发生在 Corepack 获取 Yarn 还是 Yarn 获取项目依赖。 Corepack cache 没有目标包管理器版本，或 archive 预热了错误版本。 在线环境按项目 packageManager 重新 corepack pack，离线用 --cache-only 导入。 网络禁用时 yarn --version 和不可变依赖安装都成功。
签名校验失败
下载成功但 Corepack 报 keyid、signature 或 integrity 错误。 比较官方 registry 与企业镜像，检查 Corepack 版本、系统时间和代理响应。 旧 Corepack 不认识新密钥、镜像元数据不完整、代理改写或缓存损坏。 升级到批准的兼容 Corepack，修复镜像同步并重新预热；不禁用完整性检查。 清洁缓存下在线校验成功，再在离线 archive 上复验。
Windows 更新后 shim 又变了
npm 安装的 Corepack 曾正常，Node MSI 修复或升级后命令来源改变。 用 Get-Command corepack -All 和系统应用组件检查来源。 Windows Installer 管理的 Corepack feature 与 npm 全局安装争用同一文件位置。 选择一种所有权；按官方说明修改 MSI feature 后再由 npm 管理，或完全交还安装器。 执行系统修复/升级演练后，命令路径和版本仍符合资产清单。
Node 升级会同时移动三层边界
Node 大版本可能改变 Corepack 是否随附、全局安装目录和目标包管理器的运行时兼容性。升级计划必须分别验证 Node、Corepack 和 Yarn/pnpm，而不是只跑应用测试。Node 25 的分发变化证明“以前自带”不是长期承诺。
shim 的所有权决定能否稳定升级
系统包、Node 版本管理器、MSI、npm 全局目录和自定义 bin 都可能创建同名命令。团队要规定谁拥有 shim、如何更新和如何回滚；否则一次系统修复就可能静默替换版本代理。资产采集应记录解析路径，不只记录版本字符串。
Known Good Release 会制造无项目漂移
没有 packageManager 的脚本、临时目录和初始化任务可能使用 Corepack 默认版本，并在联网时更新同 major。任何需要可复现的自动化都应先进入有契约的项目，或显式指定批准版本；Known Good Release 只作为交互式兜底。
离线交付必须分两级缓存
Corepack cache 保存包管理器本体，Yarn/pnpm cache 保存项目依赖。只准备其中一层，离线构建仍会失败。验收必须在网络真正禁用时分别运行版本命令和依赖安装，并对 archive、lockfile 和缓存设独立校验与保留策略。
签名轮换考验升级响应
旧 Corepack 遇到新 registry 签名时可能阻断所有构建。团队需要监控官方变更、维护可快速升级的基础镜像，并保留经验证的离线 archive。把完整性检查全局关闭会把可用性故障升级成供应链失控。
环境变量既是控制面也是泄露面
COREPACK_NPM_TOKEN、代理 URL、用户名密码和自定义 registry 都可能进入进程列表、调试日志或镜像层。CI 应使用 Secret 注入和日志掩码，开发机使用凭证管理器；排障收集环境时只列变量名和是否设置，不回显值。
Corepack 本身也要有退出方案
实验能力意味着团队必须能迁出。退出时要选择替代入口，例如项目内 binary、受控镜像直接安装精确 Yarn/pnpm，或语言环境管理工具；随后在代表性项目验证版本、锁文件和 CI。不能先卸载 Corepack，再临时恢复全局 latest。
团队治理基线
Corepack 自身使用批准的精确版本和可信安装来源，Node 25 后显式安装。每个仓库提交 packageManager 精确版本，不依赖 Known Good Release。shim 只有一个明确所有者：系统安装、Node 管理器、npm 全局或受控 bin 选其一。
本地与 CI 打印 Node、Corepack、包管理器版本并调用同一不可变安装入口。在线、代理、企业 CA、私有 registry 与离线模式分别有最小验证。Corepack archive 和项目依赖 cache 分层管理、校验、扫描和保留。
签名失败禁止以关闭完整性检查作为长期方案。凭证只由 Secret 系统或开发机凭证链注入，日志和镜像层不得出现明文。Node/Corepack/包管理器升级拆分验证，保留上一批准镜像和回滚步骤。
每年至少复核一次 Corepack 实验状态、Node 分发边界和替代方案。
已确认当前 Node 是否随附 Corepack，没有假设 Node 25+ 仍内置。Corepack 的来源、精确版本、命令路径和升级责任人可追溯。corepack enable 创建的 shim 目录明确且权限最小。
已清理或隔离抢占 PATH 的全局 Yarn/pnpm。每个项目的 packageManager 固定精确版本并进入代码审查。没有把 Known Good Release 当作项目可复现契约。
CI 显式准备或验证 Corepack，不依赖 runner 偶然状态。离线验收同时覆盖包管理器 archive 和项目依赖 cache。代理、CA、registry 与凭证按 Corepack层和包管理器层分别配置。
signature/integrity 故障有升级和镜像修复路径，未关闭校验。cache 清理前保留版本与错误证据，未删除项目 lockfile。已演练 corepack disable、卸载和替代入口，不会让全部仓库停摆。
入口契约出问题时查哪里
Corepack 是否随当前 Node 分发、怎样独立安装、shim 与缓存命令如何变化，查 Node.js Corepack 仓库与使用说明。packageManager 和 devEngines.packageManager 的运行时语义有疑问时，查 Node.js Packages：packageManager 字段。
Yarn 没有按项目声明启动，或 yarn set version 改写结果不符合预期时，查 Yarn Corepack 说明、Yarn Installation、Yarn Manifest：packageManager 和 yarn set version。