1. 问题现象与初步排查当你尝试用SSH协议推送代码到GitHub时遇到Permission denied错误而HTTPS方式却可以正常操作这种问题通常出现在以下几种场景本地SSH密钥对未正确配置GitHub账户未添加公钥或添加有误SSH服务端配置存在问题网络环境对SSH协议有特殊限制首先我们需要确认错误的具体表现。典型的SSH连接失败会显示类似这样的信息gitgithub.com: Permission denied (publickey). fatal: Could not read from remote repository.而HTTPS方式能正常工作说明你的Git账户基础配置是正确的你有该仓库的访问权限网络连接本身没有问题关键提示在开始排查前请先用ssh -T gitgithub.com测试基础连接性。这个命令会返回更详细的错误信息比git push的报错更有诊断价值。2. SSH密钥配置全流程检查2.1 密钥对生成验证首先检查本地是否存在可用的SSH密钥对ls -al ~/.ssh正常应该能看到id_rsa和id_rsa.pub文件如果你使用RSA算法或者id_ed25519和id_ed25519.pub如果使用Ed25519算法。如果没有密钥对需要重新生成ssh-keygen -t ed25519 -C your_emailexample.com推荐使用Ed25519算法比传统RSA更安全高效生成过程中注意不要直接回车跳过密码设置建议设置强密码密钥文件建议保持默认路径生成后验证密钥指纹ssh-keygen -l -f ~/.ssh/id_ed255192.2 公钥上传GitHub的正确姿势很多人在GitHub添加公钥时容易犯以下错误复制了私钥内容文件没有.pub后缀的公钥内容格式被破坏比如用富文本编辑器打开导致换行符变化添加到了错误的账户位置个人账户 vs 组织账户正确操作步骤用以下命令精确复制公钥内容cat ~/.ssh/id_ed25519.pub | clip # Windows pbcopy ~/.ssh/id_ed25519.pub # Mac登录GitHub → Settings → SSH and GPG keys → New SSH keyTitle字段建议用设备名_用途格式如MBP2023_DevelopmentKey type保持默认的Authentication Key粘贴时确保没有多余空格或换行常见陷阱某些终端工具如VS Code内置终端可能在复制时自动添加隐藏字符建议用系统原生终端操作。3. SSH配置深度调优3.1 多账户场景的config配置如果你在多个Git平台GitHub、GitLab等使用不同密钥需要配置~/.ssh/config文件Host github.com HostName github.com User git IdentityFile ~/.ssh/github_ed25519 IdentitiesOnly yes AddKeysToAgent yes Host gitlab.example.com HostName gitlab.example.com User git IdentityFile ~/.ssh/gitlab_rsa关键参数说明IdentitiesOnly yes强制使用指定密钥避免SSH尝试所有可用密钥AddKeysToAgent yes自动将密钥加载到ssh-agent每个Host块对应不同的代码托管平台3.2 SSH-Agent的正确使用姿势为了避免每次push都输入密钥密码# 启动ssh-agent eval $(ssh-agent -s) # 添加密钥到agent ssh-add ~/.ssh/id_ed25519 # 查看已加载密钥 ssh-add -lWindows用户特别注意Git Bash自带的ssh-agent可能与系统服务冲突推荐使用管理员权限运行net start ssh-agent4. 网络层问题排查4.1 防火墙与代理配置某些企业网络会限制SSH的22端口。GitHub实际上也支持通过HTTPS端口443进行SSH操作Host github.com HostName ssh.github.com User git Port 443 IdentityFile ~/.ssh/id_ed25519测试连接ssh -T gitgithub.com -p 4434.2 SSH连接详细诊断使用-v参数获取详细日志ssh -Tv gitgithub.com重点关注以下信息实际使用的密钥路径Offering public key...服务器接受的认证方式Authentications that can continue...错误发生的具体阶段5. 进阶问题与解决方案5.1 密钥格式兼容性问题如果你从旧系统迁移密钥可能会遇到Load key /path/to/key: invalid format解决方法# 转换传统PEM格式 ssh-keygen -p -f ~/.ssh/id_rsa -m pem # 或者生成新格式密钥 ssh-keygen -o -f ~/.ssh/id_rsa5.2 双因素认证(2FA)的影响启用2FA后SSH操作不受影响与HTTPS不同但如果你同时配置了GitHub App权限Fine-grained personal access tokens可能需要检查令牌的权限范围是否包含仓库访问。5.3 仓库remote URL验证检查你的本地仓库配置git remote -v确保SSH格式为gitgithub.com:username/repo.git而非错误的git://github.com/username/repo.git转换方法git remote set-url origin gitgithub.com:username/repo.git6. 平台特定问题排查6.1 GitHub企业版差异如果你使用的是GitHub Enterprise需要注意可能使用自定义SSH端口证书签名可能不同需要配置自定义CA证书诊断命令ssh -Tv gityour.ghe.domain.com6.2 CI/CD环境中的SSH问题在GitHub Actions等环境中SSH密钥需要作为Repository Secret存储使用特殊格式的known_hostsmkdir -p ~/.ssh ssh-keyscan github.com ~/.ssh/known_hosts工作流中正确加载- uses: webfactory/ssh-agentv0.7.0 with: ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}7. 终极排查清单当所有方法都尝试后仍不工作按此清单逐步检查[ ]ssh -Tv gitgithub.com输出是否显示尝试了正确的密钥[ ] GitHub账户设置中公钥指纹是否与本地ssh-keygen -l显示一致[ ] 本地~/.ssh目录权限是否为700密钥文件权限是否为600[ ] 是否在多个终端窗口同时运行ssh-agent导致冲突[ ] 尝试临时关闭防火墙/杀毒软件测试[ ] 使用其他网络环境如手机热点测试[ ] 创建全新测试密钥对验证基础功能我在管理多个Git账户时发现最容易出错的是~/.ssh/config中的Host定义。曾经因为一个配置块中多了一个空格字符导致整个SSH认证失败。现在我会用ssh -G github.com命令验证实际生效的配置参数这个方法帮我节省了大量调试时间。