Git 报错解决：SSH 公钥认证失败（Permission denied (publickey)）
在通过 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 密钥对（无公钥/私钥可供认证）；
- 本地已生成 SSH 密钥，但公钥未添加到你的 GitHub 账号中；
- 本地存在多个 SSH 密钥，未配置密钥映射，导致 Git 使用了错误的密钥进行认证；
- 生成的 SSH 密钥格式不被 GitHub 支持（推荐 ED25519 或 RSA 格式）。
三、解决方案（两种方案，按需选择）
方案 1：配置 SSH 密钥（永久解决，推荐长期使用）
该方案通过生成 SSH 密钥对，并将公钥添加到 GitHub 账号，实现永久免密认证，后续操作 SSH 协议仓库无需重复验证。
步骤 1：生成 SSH 密钥对
- 执行后终端会出现一系列交互提示，全部按回车默认即可：
- 提示「Enter file in which to save the key」：默认存储路径（Windows 为
C:\Users\你的用户名\.ssh\，Mac/Linux 为~/.ssh/），无需修改； - 提示「Enter passphrase」：密钥密码（留空则无需密码，后续操作无需输入，推荐新手留空）；
- 提示「Enter same passphrase again」：重复密钥密码，留空则直接回车。
- 提示「Enter file in which to save the key」：默认存储路径（Windows 为
- 执行完成后，会在默认存储路径下生成两个文件（无后缀为私钥，
.pub后缀为公钥）：- 私钥：
id_ed25519（核心机密，切勿泄露、删除或修改）； - 公钥：
id_ed25519.pub（用于上传到 GitHub，可公开分享）。
- 私钥：
打开 Git Bash（Windows）或 Terminal（Mac/Linux），执行以下命令生成 ED25519 格式密钥（安全性更高，推荐），替换为你的 GitHub 注册邮箱：
ssh-keygen -t ed25519 -C "你的 GitHub 注册邮箱@example.com"
