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 [email protected]
      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": "[email protected]"
}

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

  corepack prepare [email protected] --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