修复推送到 GitHub 时的 'Permission denied (publickey)' 错误

在尝试推送到 GitHub 时遇到 ‘Permission denied (publickey)’ 错误?这个错误意味着 GitHub 由于 SSH 密钥问题无法对你进行身份验证。让我们快速修复它。
关键要点
- 当 GitHub 无法验证你的 SSH 连接时会出现此错误
- 三个主要原因:缺少 SSH 密钥、密钥未添加到 GitHub,或远程 URL 格式不正确
- 使用
ssh -T git@github.com
测试你的连接以验证修复是否有效 - SSH agent 和配置文件有助于管理多个账户或持久身份验证
这个错误的含义
当 Git 尝试使用 SSH 连接到 GitHub,但身份验证失败时,就会出现 ‘Permission denied (publickey)’ 错误。可以把 SSH 密钥想象成一个特殊的密码,让你的计算机能够安全地与 GitHub 通信。
本指南涵盖了三个主要原因,并准确展示如何修复每一个问题。
三个主要原因(以及如何修复)
1. 计算机上未创建 SSH 密钥
快速检查:
ls -la ~/.ssh
如果你看到 “No such file or directory” 或文件夹为空,则需要创建 SSH 密钥。
修复方法: 生成新的 SSH 密钥对:
ssh-keygen -t ed25519 -C "your-email@example.com"
按三次回车键接受默认设置。这将创建两个文件:
~/.ssh/id_ed25519
(私钥 - 保密)~/.ssh/id_ed25519.pub
(公钥 - 与 GitHub 共享)
2. 公钥未添加到 GitHub
即使创建了 SSH 密钥,在你将公钥添加到账户之前,GitHub 也无法识别你。
修复方法: 首先,复制你的公钥:
cat ~/.ssh/id_ed25519.pub
然后将其添加到 GitHub:
- 访问 GitHub SSH 设置
- 点击 “New SSH key”
- 粘贴你的密钥并保存
3. 远程 URL 格式错误
GitHub SSH URL 必须以 git@github.com:
开头 - 而不是你的邮箱或用户名。
检查当前 URL:
git remote -v
正确格式:
git@github.com:username/repository.git
错误格式:
youremail@github.com:username/repository.git ❌
https://github.com/username/repository.git ❌ (这是 HTTPS,不是 SSH)
修复方法: 更新为正确的 SSH URL:
git remote set-url origin git@github.com:username/repository.git
Discover how at OpenReplay.com.
验证一切正常
测试你与 GitHub 的 SSH 连接:
ssh -T git@github.com
你应该看到:
Hi username! You've successfully authenticated...
如果成功,你现在可以推送到 GitHub 而不会出现权限被拒绝的错误。
常见故障排除问题
SSH Agent 未运行
如果你的密钥存在但仍然无法工作,SSH agent 可能没有运行。
修复方法:
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
多个 GitHub 账户
管理多个账户需要一个 SSH 配置文件。创建 ~/.ssh/config
:
Host github.com-work
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_work
Host github.com-personal
HostName github.com
User git
IdentityFile ~/.ssh/id_ed25519_personal
然后使用以下方式克隆:
git clone git@github.com-work:company/repository.git
平台特定说明
- Windows 用户: 使用 Git Bash 而不是命令提示符或 PowerShell
- macOS/Linux 用户: 使用终端
两个平台都遵循上面显示的相同命令。
结论
‘Permission denied (publickey)’ 错误虽然令人沮丧,但很容易修复。在大多数情况下,你只需要创建 SSH 密钥并将公钥添加到 GitHub。记得在推送之前使用 ssh -T git@github.com
验证你的连接。
一旦正确设置,你将不会再为该仓库看到此错误。
常见问题
虽然技术上可行,但最佳实践是为每个账户创建单独的密钥对。这提高了安全性,并使管理不同仓库时的故障排除更容易。
SSH 一旦配置完成会更方便,因为每次推送时不需要密码。HTTPS 在任何地方都可以工作,但每次操作都需要身份验证令牌或密码。
不需要。使用 ssh-add 将你的密钥添加到 SSH agent 以缓存会话的密码短语。这样你每个会话只需输入一次。
立即生成新的密钥对并使用新的公钥更新 GitHub。从 GitHub 设置中删除被泄露的密钥,永远不要分享私钥。
Understand every bug
Uncover frustrations, understand bugs and fix slowdowns like never before with OpenReplay — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.