一、前言
最近在部署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的底层逻辑：
- SSH验证原理：GitHub通过SSH密钥对（公钥+私钥）验证用户身份——本地生成密钥对后，将公钥配置到GitHub账户，克隆/推送代码时，GitHub服务器会校验本地私钥与账户公钥是否匹配，匹配成功才允许操作。
- 报错本质：
Permission denied (publickey)意味着GitHub服务器未在你的账户中找到匹配的SSH公钥，无法确认你的身份，因此拒绝了SSH连接请求。 - 常见诱因：
- 本地未生成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账户
打开GitHub官网，登录后点击右上角头像 →
Settings（设置）；
在左侧菜单找到
SSH and GPG keys→ 点击New SSH key；
Title栏填写标识（如“工作机-2026”），Key栏粘贴复制的公钥内容；
点击
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
四、总结
- 报错核心原因：本地SSH公钥未配置到GitHub账户，导致GitHub无法验证身份，拒绝SSH连接。
- 方案选择建议：临时克隆公开仓库选HTTPS方式（快速），长期开发/操作私有仓库选SSH配置（便捷、安全）。
- 额外注意点：配置SSH后若仍报错，可检查密钥文件权限（私钥需设为600）、SSH Agent是否正常运行，或更换RSA算法重新生成密钥。
希望本文能帮助大家快速解决git@github.com: Permission denied (publickey)问题，如果你有其他解决思路，欢迎在评论区交流～
