报错解决：git clone git@github.com: Permission denied (publickey)权限拒绝问题

一、前言

最近在部署detectron2（Facebook开源的目标检测框架）时，执行克隆命令：

git clone git@github.com:facebookresearch/detectron2.git

终端直接抛出如下错误：

Cloning into 'detectron2'...
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

起初以为是仓库权限问题，但detectron2是公开仓库，任何人都可克隆，排查后发现核心是SSH身份验证环节出了问题。本文将完整还原问题分析和解决过程，帮助遇到同类报错的开发者少走弯路。

二、问题分析

要理解这个报错，首先要明白Git通过SSH协议访问GitHub的底层逻辑：

1. SSH验证原理：GitHub通过SSH密钥对（公钥+私钥）验证用户身份——本地生成密钥对后，将公钥配置到GitHub账户，克隆/推送代码时，GitHub服务器会校验本地私钥与账户公钥是否匹配，匹配成功才允许操作。
2. 报错本质：Permission denied (publickey) 意味着GitHub服务器未在你的账户中找到匹配的SSH公钥，无法确认你的身份，因此拒绝了SSH连接请求。
3. 常见诱因：
   • 本地未生成SSH密钥对；
   • 生成了密钥对但未将公钥添加到GitHub账户；
   • SSH agent未启动，或未将私钥添加到agent中；
   • 密钥文件路径/权限配置错误（如私钥权限过宽）。

三、解决方案

针对该问题，提供两种解决方案：「快速临时方案」（改用HTTPS克隆）和「长期根治方案」（配置SSH密钥），可根据实际需求选择。

方案1：快速解决——改用HTTPS协议克隆（无需配置SSH）

这是最便捷的临时方案，跳过SSH验证，直接使用HTTPS协议克隆仓库，适合临时克隆公开仓库的场景。

执行如下命令即可：

git clone https://github.com/facebookresearch/detectron2.git

注意事项：

• 如果克隆时提示输入GitHub账号密码：
  • 账号填写你的GitHub用户名；
  • 若开启了GitHub两步验证（2FA），密码不能填登录密码，需使用「个人访问令牌（PAT）」代替。
• 生成PAT的步骤：GitHub首页 → 右上角头像 → Settings → Developer settings → Personal access tokens → Generate new token → 勾选repo权限 → 生成后复制令牌（仅显示一次，需妥善保存）。

方案2：长期根治——配置SSH密钥（推荐）

如果需要长期使用SSH协议操作GitHub（如频繁推送代码、克隆私有仓库），建议配置SSH密钥，一劳永逸解决身份验证问题，步骤如下：

步骤1：检查本地是否已有SSH密钥

首先查看本地.ssh目录下是否有现成的密钥文件（如id_rsa.pub/id_ed25519.pub，.pub后缀为公钥，无后缀为私钥）：

ls -al ~/.ssh

如果输出中有id_ed25519.pub或id_rsa.pub，说明已有密钥对，可跳过步骤2；若为空，需生成新密钥。

步骤2：生成新的SSH密钥（无密钥时执行）

使用ssh-keygen生成密钥对（推荐使用更安全的ed25519算法），替换为你的GitHub注册邮箱：

ssh-keygen -t ed25519 -C "your_email@example.com"

执行后按提示操作：

• 按回车默认保存路径（~/.ssh/id_ed25519），无需修改；
• 可选设置密钥密码（按回车跳过即可，设置后每次使用SSH需输入密码，更安全）。
  

步骤3：启动SSH Agent并添加私钥

SSH Agent用于管理私钥，避免每次操作都输入密钥密码，执行如下命令：

# 启动ssh-agent
eval "$(ssh-agent -s)"
# 添加私钥（若为rsa密钥，替换为id_rsa）
ssh-add ~/.ssh/id_ed25519

步骤4：复制SSH公钥内容

执行命令复制公钥文本（后续需粘贴到GitHub）：

cat ~/.ssh/id_ed25519.pub

复制输出的全部内容（以ssh-ed25519开头，你的邮箱结尾的完整字符串）。

步骤5：将公钥添加到GitHub账户

1. 打开GitHub官网，登录后点击右上角头像 → Settings（设置）；
   

2. 在左侧菜单找到SSH and GPG keys → 点击New SSH key；
   

3. Title栏填写标识（如“工作机-2026”），Key栏粘贴复制的公钥内容；
   

4. 点击Add SSH key完成添加（若开启2FA，需验证身份）。
   

步骤6：验证SSH连接

执行如下命令验证配置是否成功：

ssh -T git@github.com

若终端输出Hi [你的GitHub用户名]! You've successfully authenticated, but GitHub does not provide shell access.，说明SSH配置成功。

步骤7：重新克隆仓库

此时再执行原SSH克隆命令，即可正常克隆：

git clone git@github.com:facebookresearch/detectron2.git

四、总结

1. 报错核心原因：本地SSH公钥未配置到GitHub账户，导致GitHub无法验证身份，拒绝SSH连接。
2. 方案选择建议：临时克隆公开仓库选HTTPS方式（快速），长期开发/操作私有仓库选SSH配置（便捷、安全）。
3. 额外注意点：配置SSH后若仍报错，可检查密钥文件权限（私钥需设为600）、SSH Agent是否正常运行，或更换RSA算法重新生成密钥。

希望本文能帮助大家快速解决git@github.com: Permission denied (publickey)问题，如果你有其他解决思路，欢迎在评论区交流～