GitHub Actions安装NPM依赖校验失败、SSH公钥报错排查

核心根因：依赖项buble@git+ssh://git@github.com/pemrouz/buble.git#4e639ae采用Git协议直接拉取指定commit，该仓库对应commit的打包产物存在非确定性，不同环境拉取得到的文件内容不一致，直接导致sha512校验值随机不匹配；现有Git URL替换规则未覆盖git+ssh格式地址，导致npm始终走SSH协议拉取，Runner无对应SSH私钥时触发公钥权限报错。

1. 内置buble包避免每次构建重复拉取 #

可选两种稳定方案：

• 本地vendor目录托管
  本地执行命令将对应版本buble下载到项目内的vendor目录，修改依赖声明为本地路径，彻底跳过远程拉取：

  # 项目根目录执行
  mkdir -p vendor
  cd vendor
  git clone https://github.com/pemrouz/buble.git
  cd buble
  git checkout 4e639aeeb64712ac95dc30a52750d1ee4432c9c8
  npm install --production
  

  回到项目根目录，修改package.json中buble的依赖项为"buble": "file:./vendor/buble"，删除旧的node_modules和package-lock.json后重新执行npm install生成新的lock文件，将vendor/buble目录、更新后的依赖配置文件一并提交到仓库即可。
• GitHub Actions缓存
  在工作流的依赖安装步骤前加缓存配置，首次构建成功后后续执行直接读取本地缓存，无需重复拉取：

  - name: 缓存NPM依赖
    uses: actions/cache@v3
    with:
      path: node_modules
      key: ${{ runner.os }}-node-${{ hashFiles('package-lock.json') }}
  

  注意该方案在package-lock.json变更时会自动失效，需要重新拉取依赖，稳定性弱于本地vendor方案。

2. 彻底修复校验值不匹配问题 #

禁止手动修改package-lock.json内的校验值，按以下步骤从根源修复：

• 第一步补全Git地址替换规则，原有规则仅匹配ssh://开头的地址，未覆盖git@github.com:简写和git+ssh://格式，替换规则修改为：

  - name: 强制使用HTTPS拉取GitHub仓库
    run: |
      git config --global url."https://github.com/".insteadOf ssh://git@github.com/
      git config --global url."https://github.com/".insteadOf git@github.com:
      git config --global url."https://github.com/".insteadOf git+ssh://git@github.com/
  

• 第二步删除本地旧的node_modules目录和package-lock.json文件，重新执行npm install生成全新的lock文件，此时buble依赖会通过HTTPS协议拉取。
• 最优方案：替换Git源依赖为固定版本包。尽量使用npm官方源发布的正式版本buble，官方源的包为固定tarball，校验值永久不变；如果必须使用该fork版本的特定commit，可以自行打包后发布到私有npm源，后续依赖私有源的固定版本，彻底规避Git拉取的非确定性问题。
• 临时绕过方案（不推荐长期使用）：执行npm install时添加--no-integrity参数跳过完整性校验，该方案会引入供应链安全风险，仅作临时调试用。

3. SSH公钥权限拒绝问题修复 #

该报错本质是Git地址替换规则不全，npm拉取依赖时仍走SSH协议，而GitHub Actions的macOS Runner默认没有配置对应GitHub仓库的SSH访问私钥，直接按以下两种方案修复即可：

• 优先方案：按问题2中的配置补全Git全局替换规则，所有GitHub Git地址全部走HTTPS协议拉取，公开仓库HTTPS拉取无需配置任何密钥，可直接解决权限问题。
• 若必须走SSH协议拉取私有依赖：在项目仓库的Secrets中添加拥有对应仓库访问权限的SSH私钥，在npm install步骤前添加SSH配置步骤：

  - name: 配置SSH访问密钥
    run: |
      mkdir -p ~/.ssh
      echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_rsa
      chmod 600 ~/.ssh/id_rsa
      ssh-keyscan github.com >> ~/.ssh/known_hosts
  

内容的提问来源于stack exchange，提问作者Chris T