GitHub Actions上关于“Cannot Find Matching Keyid”或“Corepack/PNPM Not Found”的错误

如何使用 GitHub 操作调试并解决此 corepack 问题。

如果你的构建突然出现 cannot find matching keyid: {"signatures":[...],"keys":[...]} 这样的失败信息，通常意味着 npm 注册表键值已被轮换，而你的旧 Corepack 无法验证 pnpm 的新版本（如 9.15.4 或 10.1.0+）。

这种情况可能发生在 GitHub Actions、GitLab、Docker 或其他使用 Corepack 管理软件包管理器的地方。

¶快速调试步骤

1. 检查 Node.js 版本： node -v （如果您看到 v16.x ，则您使用的是 Node 16；如果您看到 v18.x 或更高版本，则您使用的是 Node 18+）。
2. 检查 Corepack 版本： corepack --version. 任何早于 0.31.0 的版本都可能没有新的密钥集。
3. 查找条件逻辑。有些工作流程只在 Node 16 上更新 Corepack。如果您在 Node 18+ 上构建，该逻辑可能会完全跳过更新。

¶如何修复

¶如果您使用的是 18+ 节点（或更新版本）

升级到最新的 Corepack (≥ 0.31.0 )：

steps:
  - name: Pin Corepack 0.20
    run: |
      echo "Before: corepack => $(corepack --version || echo 'not installed')"
      npm install -g corepack@0.20
      echo "After : corepack => $(corepack --version)"
      corepack enable
      pnpm --version

这将确保你拥有与 npm 注册表变更相匹配的新签名密钥。

下载 Node.js v22.14.0版本解决

使用 corepack enable pnpm 的完整指南

corepack 是 Node.js 内置的包管理器管理工具（从 Node.js v16.9.0 开始实验性支持，v16.13.0+ 稳定）。它允许开发者在不全局安装包管理器（如 pnpm、yarn）的情况下，通过项目配置直接使用特定版本的包管理器。以下是详细使用 corepack enable pnpm 的步骤和说明。

1. 前置条件

• 确保 Node.js 版本 ≥ v16.9.0（实验性支持）或 ≥ v16.13.0（稳定支持）。

• 如果使用旧版 Node.js，需手动升级：

  # 使用 nvm 管理 Node.js 版本（推荐）
  nvm install 18.0.0  # 安装最新 LTS 版本
  nvm use 18.0.0
  

2. 启用 Corepack

在终端中运行以下命令启用 corepack：

corepack enable

此命令会：

1. 激活 corepack 功能。
2. 在系统路径中创建 pnpm、yarn 等命令的代理脚本。
3. 允许通过项目配置或命令指定包管理器版本。

3. 启用 pnpm

通过以下命令启用 pnpm：

corepack enable pnpm

• 如果之前已全局安装过 pnpm，可能需要添加 --force 覆盖：

  corepack enable pnpm --force
  

• 此命令会：

  • 在系统中注册 pnpm 的代理脚本。
  • 默认使用 corepack 管理的 pnpm 版本（通常为最新稳定版）。

4. 验证安装

检查 pnpm 是否成功启用：

pnpm --version
# 输出示例：8.15.0

如果看到版本号，说明 pnpm 已通过 corepack 启用。

5. 指定 pnpm 版本

若需在项目中固定 pnpm 版本，可在 package.json 中添加 packageManager 字段：

{
  "packageManager": "pnpm@8.15.0"
}

• 运行以下命令让 corepack 准备指定版本的 pnpm：

  corepack prepare pnpm@8.15.0 --activate
  

• 此后，在项目目录中执行 pnpm 时会自动使用指定版本。

6. 使用 pnpm 命令

现在可以像全局安装一样使用 pnpm：

# 初始化项目
pnpm init

# 安装依赖
pnpm install

# 运行脚本
pnpm run dev

# 全局模式（需单独配置）
pnpm add -g some-package

7. 升级 pnpm 版本

通过 corepack 升级到最新版：

corepack prepare pnpm@latest --activate

8. 禁用 pnpm

如果需要恢复默认行为（如使用全局安装的 pnpm）：

corepack disable pnpm

常见问题

Q1: 权限错误（Permission Denied）

• 现象：执行 corepack enable 时报权限错误。

• 解决：

  # 使用 sudo（不推荐，尽量用非 root 用户）
  sudo corepack enable
  
  # 或修复 npm 目录权限
  sudo chown -R $USER:$(id -gn $USER) ~/.npm