SSH 连接 Git 报 Permission denied (publickey) 怎么办？一套排查清单

使用 Git 拉取或推送代码时，最让人困惑的错误之一就是 Permission denied (publickey)。仓库地址看起来没错，账号也能登录网页，但命令行就是连不上。这个问题不要靠猜，我们按一条线排：本地有没有密钥、密钥有没有被 SSH 代理加载、远端是否保存了对应公钥、当前仓库到底连到了哪个主机。

本文适合正在用 SSH 方式访问 Git 仓库的开发者。下面的命令以 macOS/Linux 终端为例，Windows 用户如果使用 Git Bash，也可以按同样思路检查。

问题现场：SSH 提示 publickey 被拒绝

我们先看现象。执行 git pull 或 git push 后，终端返回类似下面的内容：

Permission denied (publickey).
fatal: Could not read from remote repository.

这句话的重点不是“仓库不存在”，而是远端没有接受当前这把 SSH 密钥。换句话说，请求已经到了认证阶段，但服务器没有找到可以证明你身份的公钥。

初步判断：先确认仓库地址走的是 SSH

第一步先看仓库远端地址。如果地址是 https://...，那排查重点是账号令牌或凭据缓存；如果是 git@...，才是本文讨论的 SSH 密钥问题。

git remote -v

常见 SSH 地址长这样：

origin  git@example.com:team/project.git (fetch)
origin  git@example.com:team/project.git (push)

如果远端地址已经是 SSH，再进入下一步。这里不要急着重新生成密钥，很多时候只是本机没有把正确私钥交给 SSH 客户端。

动手验证：检查本地密钥和代理状态

接着验证本机有没有可用密钥。先列出 ~/.ssh 目录：

ls -al ~/.ssh

一般会看到成对文件，例如 id_ed25519 和 id_ed25519.pub，其中不带 .pub 的是私钥，带 .pub 的是公钥。私钥留在本地，公钥复制到 Git 平台账号里。

再看当前代理里加载了哪些密钥：

ssh-add -l

如果输出提示没有身份信息，说明 SSH 客户端当前没有拿到可用私钥。此时即使你的 ~/.ssh 目录里有密钥，连接也可能失败。

定位原因：本地私钥和远端公钥没有对上

现在可以把原因缩小到四类：

• 本地没有生成 SSH 密钥，或者密钥放在了非默认文件名里。
• 本地有私钥，但没有加入 SSH 代理。
• 远端 Git 平台没有保存对应的公钥。
• 同一台电脑配置了多个 Git 账号，Host 规则没有指到正确私钥。

如果你有多把密钥，尤其要看 ~/.ssh/config。一个常见场景是公司账号和个人账号都在同一台电脑上，默认私钥被拿去连了另一个账号，远端自然会拒绝。

修复方案：加载正确密钥并验证远端身份

修复不要乱改，按顺序来：先确认密钥文件，再加入代理，然后为具体主机指定私钥，最后做连接测试。

ssh-add ~/.ssh/id_ed25519

如果你有多套账号，可以在 ~/.ssh/config 中明确指定：

Host git-work
  HostName example.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work
  IdentitiesOnly yes

配置后，仓库地址也要配合使用这个 Host：

git remote set-url origin git@git-work:team/project.git

这样 SSH 客户端会按 git-work 这条规则选择私钥，而不是把默认密钥挨个试一遍。

验证结果：测试连接后再拉取或推送

最后确认，不要直接反复推送。先用 SSH 测试连接：

ssh -T git@git-work

如果返回欢迎信息、认证成功提示，或者明确说明该服务不提供 shell 访问但身份已通过，就说明密钥链路已经通了。然后再执行：

git pull
git push

如果测试连接成功但 Git 仍然失败，继续检查仓库地址是否仍指向旧 Host、当前分支是否有权限、项目是否已经被迁移或归档。

常见误区与总结清单

常见误区有三个。第一，把公钥和私钥搞反，把私钥复制到了网页上，这是非常危险的；第二，生成了新密钥，却没有把新公钥添加到 Git 平台；第三，多账号环境里没有写 Host 规则，导致 SSH 客户端拿错密钥。

总结一下：Permission denied (publickey) 的核心是“远端没有认可当前密钥”。排查时顺着链路走：仓库地址是否是 SSH、本地是否有密钥、代理是否加载、远端是否保存公钥、Host 是否指向正确私钥。链路每一段都确认后，这个问题通常很快就能收住。