【Git 报错解决】SSH 公钥认证失败（`Permission denied (publickey)`）

Git 报错解决：SSH 公钥认证失败（Permission denied (publickey)）

在通过 SSH 协议操作 GitHub 远程仓库（克隆、拉取、推送）时，经常会遇到 Permission denied (publickey) 报错，这是新手配置 Git 与 GitHub 连接时的高频问题。本文将详细拆解报错原因、两种高效解决方法（永久/临时），以及验证和避坑技巧，通用可直接复用。

一、报错场景还原

执行涉及 SSH 协议的 Git 命令时触发报错，常见场景包括：

# 场景1：克隆远程仓库
git clone git@github.com:用户名/仓库名.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 密钥验证你的账号身份，从而拒绝你的仓库访问请求。常见具体原因包括：

1. 本地未生成任何 SSH 密钥对（无公钥/私钥可供认证）；
2. 本地已生成 SSH 密钥，但公钥未添加到你的 GitHub 账号中；
3. 本地存在多个 SSH 密钥，未配置密钥映射，导致 Git 使用了错误的密钥进行认证；
4. 生成的 SSH 密钥格式不被 GitHub 支持（推荐 ED25519 或 RSA 格式）。

三、解决方案（两种方案，按需选择）

方案1：配置 SSH 密钥（永久解决，推荐长期使用）

该方案通过生成 SSH 密钥对，并将公钥添加到 GitHub 账号，实现永久免密认证，后续操作 SSH 协议仓库无需重复验证。

步骤1：生成 SSH 密钥对

1. 打开 Git Bash（Windows）或 Terminal（Mac/Linux），执行以下命令生成 ED25519 格式密钥（安全性更高，推荐），替换为你的 GitHub 注册邮箱：

   ssh-keygen -t ed25519 -C "你的GitHub注册邮箱@example.com"

2. 执行后终端会出现一系列交互提示，全部按回车默认即可 ：

   • 提示「Enter file in which to save the key」：默认存储路径（Windows 为 C:\Users\你的用户名\.ssh\，Mac/Linux 为 ~/.ssh/），无需修改；
   • 提示「Enter passphrase」：密钥密码（留空则无需密码，后续操作无需输入，推荐新手留空）；
   • 提示「Enter same passphrase again」：重复密钥密码，留空则直接回车。

3. 执行完成后，会在默认存储路径下生成两个文件（无后缀为私钥，.pub 后缀为公钥）：

   • 私钥：id_ed25519（核心机密，切勿泄露、删除或修改）；
   • 公钥：id_ed25519.pub（用于上传到 GitHub，可公开分享）。

步骤2：读取并复制公钥内容

执行以下命令，读取公钥文件的完整内容并复制：

cat ~/.ssh/id_ed25519.pub

终端会输出一串以 ssh-ed25519 开头、你的 GitHub 邮箱结尾的字符串，完整复制该字符串（不要遗漏任何字符，包括开头的协议和结尾的邮箱）。

步骤3：将公钥添加到 GitHub 账号

1. 登录你的 GitHub 账号，点击右上角头像 → 选择「Settings」（设置）；
2. 在左侧导航栏中，找到并点击「SSH and GPG keys」（SSH 和 GPG 密钥）；
3. 点击页面右上角「New SSH key」（新建 SSH 密钥）；
4. 填写密钥信息：
   • 「Title」：填写备注（如「Windows-办公电脑」「Mac-个人笔记本」，便于区分多个设备）；
   • 「Key type」：选择「Authentication key」（认证密钥）；
   • 「Key」：粘贴刚才复制的公钥完整字符串（确保无空格、无换行、无遗漏）；
5. 点击「Add SSH key」（添加 SSH 密钥），完成公钥配置（若弹出 GitHub 账号密码验证，输入密码或个人访问令牌即可）。

步骤4：验证 SSH 连接是否成功

回到 Git Bash/Terminal，执行以下命令验证与 GitHub 的 SSH 连接：

ssh -T git@github.com

1. 首次执行会提示「Are you sure you want to continue connecting (yes/no)?」，输入「yes」并回车；

2. 若终端输出以下内容，说明 SSH 认证配置成功：

   Hi 你的GitHub用户名! You've successfully authenticated, but GitHub does not provide shell access.

方案2：改用 HTTPS 链接（临时解决，快速上手）

若暂时不想配置 SSH 密钥，可直接改用 GitHub 仓库的 HTTPS 链接，绕过 SSH 认证，快速完成仓库操作。

步骤1：获取仓库的 HTTPS 链接

登录 GitHub，进入目标仓库页面，点击「Code」按钮，在弹出的窗口中切换到「HTTPS」标签，复制对应的 HTTPS 链接（格式为 https://github.com/用户名/仓库名.git）。

步骤2：替换远程仓库链接（若已关联 SSH 链接）

若本地已关联过该仓库的 SSH 链接，先修改远程仓库链接为 HTTPS 格式：

# 替换为你的仓库 HTTPS 链接
git remote set-url origin https://github.com/用户名/仓库名.git

若未关联过远程仓库，直接执行关联命令：

git remote add origin https://github.com/用户名/仓库名.git

步骤3：执行 Git 操作（拉取/推送）

后续执行拉取、推送命令即可，例如：

# 拉取远程仓库内容
git pull origin main --allow-unrelated-histories

# 推送本地内容到远程仓库
git push -u origin main

执行后会弹出登录提示，用户名输入你的 GitHub 账号名，密码输入你的 GitHub 个人访问令牌（GitHub 已不再支持直接输入账号密码，个人访问令牌需在 GitHub 账号「Settings」→「Developer settings」→「Personal access tokens」中生成，权限勾选「repo」即可）。

四、补充技巧与避坑指南

1. 多 SSH 密钥配置：若一台设备需要关联多个 GitHub 账号，需在 .ssh 目录下创建 config 文件，配置密钥与账号的映射关系，避免认证冲突；
2. 密钥丢失/失效处理：若设备重装系统、删除 .ssh 目录导致密钥丢失，只需重新生成密钥对并上传公钥到 GitHub 即可，旧公钥可在 GitHub 账号中删除；
3. 优先选择 ED25519 格式：相比传统 RSA 格式，ED25519 密钥更安全、体积更小，兼容性更好（GitHub 全面支持），避免使用过时的 DSA 格式；
4. 验证远程仓库链接：执行 Git 操作前，可通过 git remote -v 查看当前关联的远程仓库链接，确认格式正确（SSH/HTTPS 对应无误）；
5. 避免私钥泄露：私钥（id_ed25519/id_rsa）是账号认证的核心，切勿分享给他人，也不要上传到公共仓库中（可在 .gitignore 中忽略 .ssh 目录）。