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

在尝试推送到 GitHub 时遇到 ‘Permission denied (publickey)’ 错误?这个错误意味着 GitHub 由于 SSH 密钥问题无法对你进行身份验证。让我们快速修复它。

这个错误的含义

当 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:

1. 访问 GitHub SSH 设置
2. 点击 “New SSH key”
3. 粘贴你的密钥并保存

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

验证一切正常

测试你与 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 验证你的连接。

一旦正确设置,你将不会再为该仓库看到此错误。

常见问题

我可以为多个 GitHub 账户使用同一个 SSH 密钥吗?

虽然技术上可行,但最佳实践是为每个账户创建单独的密钥对。这提高了安全性,并使管理不同仓库时的故障排除更容易。

我应该为 GitHub 使用 SSH 还是 HTTPS?

SSH 一旦配置完成会更方便,因为每次推送时不需要密码。HTTPS 在任何地方都可以工作,但每次操作都需要身份验证令牌或密码。

我的 SSH 密钥有密码短语。我需要每次都输入吗?

不需要。使用 ssh-add 将你的密钥添加到 SSH agent 以缓存会话的密码短语。这样你每个会话只需输入一次。

如果我不小心分享了我的私有 SSH 密钥怎么办?

立即生成新的密钥对并使用新的公钥更新 GitHub。从 GitHub 设置中删除被泄露的密钥,永远不要分享私钥。