SSH方式执行npm run deploy部署GitHub Pages遇公钥权限拒绝问题

可能的原因及排查步骤 #

1. gh-pages工具未使用默认SSH配置 #

虽然本地git remote -v显示的是SSH地址，但gh-pages可能读取了额外配置或使用了不同的远程路径：

• 检查项目根目录是否存在.gh-pages文件或自定义gh-pages配置项，确认是否强制指定了HTTPS远程地址
• 手动指定SSH仓库地址测试：执行gh-pages -d build --repo git@github.com:your-username/repo-name.git，看是否能正常部署

2. SSH密钥未在子进程中正确加载 #

npm run deploy启动gh-pages时，子进程可能无法继承当前shell的SSH-agent环境：

• 重新加载SSH密钥：执行ssh-add ~/.ssh/id_rsa（替换为你的私钥实际路径），再运行npm run deploy
• 确保SSH-agent处于运行状态：先执行eval "$(ssh-agent -s)"启动代理，再添加密钥并测试部署

3. gh-pages版本兼容性问题 #

你使用的gh-pages 5.0.0版本可能存在SSH相关的已知问题：

• 尝试降级到稳定版本：执行npm uninstall gh-pages && npm install gh-pages@4.0.0，再测试SSH部署
• 查看gh-pages官方仓库的issues，确认是否有同类SSH权限问题的报告及修复方案

4. 仓库权限的隐性限制 #

即使ssh -T git@github.com认证成功，仍可能存在仓库级别的权限限制：

• 确认你的SSH密钥已添加到GitHub账号的SSH密钥列表（而非仅组织级别）
• 如果是组织仓库，检查是否开启了SSH密钥的组织访问权限，以及你是否拥有仓库的写入权限

总结 #

若以上步骤无法解决，可暂时保留HTTPS方式部署，通过上述排查可定位SSH失效的具体原因。

内容的提问来源于stack exchange，提问作者Colin McMurtray