Git 报错解决:SSH 公钥认证失败(Permission denied (publickey))
在通过 SSH 协议操作 GitHub 远程仓库(克隆、拉取、推送)时,经常会遇到 Permission denied (publickey) 报错,这是新手配置 Git 与 GitHub 连接时的高频问题。本文将详细拆解报错原因、两种高效解决方法(永久/临时),以及验证和避坑技巧。
一、报错场景还原
执行涉及 SSH 协议的 Git 命令时触发报错,常见场景包括:
对 Git 操作 GitHub 时出现的 Permission denied (publickey) 错误进行解析。主要原因为本地未生成 SSH 密钥、公钥未添加至 GitHub 账号或密钥配置错误。提供两种解决方案:一是生成 ED25519 格式 SSH 密钥对并上传公钥至 GitHub 实现永久免密认证;二是改用 HTTPS 链接配合个人访问令牌临时解决。文末包含多密钥配置、验证连接及避坑指南,帮助开发者快速恢复 Git 远程仓库访问。
在通过 SSH 协议操作 GitHub 远程仓库(克隆、拉取、推送)时,经常会遇到 Permission denied (publickey) 报错,这是新手配置 Git 与 GitHub 连接时的高频问题。本文将详细拆解报错原因、两种高效解决方法(永久/临时),以及验证和避坑技巧。
执行涉及 SSH 协议的 Git 命令时触发报错,常见场景包括:
# 场景 1:克隆远程仓库
git clone [email protected]:用户名/仓库名.git
# 场景 2:拉取远程仓库内容
git pull origin main
# 场景 3:推送本地内容到远程仓库
git push -u origin main
终端输出核心报错信息:
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.
该报错的本质是 SSH 身份认证失败,GitHub 无法通过你本地的 SSH 密钥验证你的账号身份,从而拒绝你的仓库访问请求。常见具体原因包括:
该方案通过生成 SSH 密钥对,并将公钥添加到 GitHub 账号,实现永久免密认证,后续操作 SSH 协议仓库无需重复验证。
C:\Users\你的用户名\.ssh\,Mac/Linux 为 ~/.ssh/),无需修改;.pub 后缀为公钥):
id_ed25519(核心机密,切勿泄露、删除或修改);id_ed25519.pub(用于上传到 GitHub,可公开分享)。打开 Git Bash(Windows)或 Terminal(Mac/Linux),执行以下命令生成 ED25519 格式密钥(安全性更高,推荐),替换为你的 GitHub 注册邮箱:
ssh-keygen -t ed25519 -C "你的 GitHub 注册邮箱@example.com"
执行以下命令,读取公钥文件的完整内容并复制:
cat ~/.ssh/id_ed25519.pub
终端会输出一串以 ssh-ed25519 开头、你的 GitHub 邮箱结尾的字符串,完整复制该字符串(不要遗漏任何字符,包括开头的协议和结尾的邮箱)。
回到 Git Bash/Terminal,执行以下命令验证与 GitHub 的 SSH 连接:
ssh -T [email protected]
若终端输出以下内容,说明 SSH 认证配置成功:
Hi 你的 GitHub 用户名!You've successfully authenticated, but GitHub does not provide shell access.
若暂时不想配置 SSH 密钥,可直接改用 GitHub 仓库的 HTTPS 链接,绕过 SSH 认证,快速完成仓库操作。
登录 GitHub,进入目标仓库页面,点击「Code」按钮,在弹出的窗口中切换到「HTTPS」标签,复制对应的 HTTPS 链接(格式为 https://github.com/用户名/仓库名.git)。
若本地已关联过该仓库的 SSH 链接,先修改远程仓库链接为 HTTPS 格式:
# 替换为你的仓库 HTTPS 链接
git remote set-url origin https://github.com/用户名/仓库名.git
若未关联过远程仓库,直接执行关联命令:
git remote add origin https://github.com/用户名/仓库名.git
后续执行拉取、推送命令即可,例如:
# 拉取远程仓库内容
git pull origin main --allow-unrelated-histories
# 推送本地内容到远程仓库
git push -u origin main
执行后会弹出登录提示,用户名输入你的 GitHub 账号名,密码输入你的 GitHub 个人访问令牌(GitHub 已不再支持直接输入账号密码,个人访问令牌需在 GitHub 账号「Settings」→「Developer settings」→「Personal access tokens」中生成,权限勾选「repo」即可)。
.ssh 目录下创建 config 文件,配置密钥与账号的映射关系,避免认证冲突;.ssh 目录导致密钥丢失,只需重新生成密钥对并上传公钥到 GitHub 即可,旧公钥可在 GitHub 账号中删除;git remote -v 查看当前关联的远程仓库链接,确认格式正确(SSH/HTTPS 对应无误);id_ed25519/id_rsa)是账号认证的核心,切勿分享给他人,也不要上传到公共仓库中(可在 .gitignore 中忽略 .ssh 目录)。
微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online
将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online
将 HTML 片段转为 GitHub Flavored Markdown,支持标题、列表、链接、代码块与表格等;浏览器内处理,可链接预填。 在线工具,HTML转Markdown在线工具,online
通过删除不必要的空白来缩小和压缩JSON。 在线工具,JSON 压缩在线工具,online
将JSON字符串修饰为友好的可读格式。 在线工具,JSON美化和格式化在线工具,online