Windows 11 环境下部署 GitHub SSH 私钥的终极指南

简介

使用 SSH 密钥连接 GitHub 是开发者首选的方式，它比 HTTPS 更安全、更便捷，可以免去重复输入用户名和密码的烦恼。本指南将详细介绍如何在 Windows 11 系统上完整地部署 SSH 私钥，并特别针对最常见的“Permission denied (publickey)”错误提供根本性的解决方案。

---

第一步：生成或准备 SSH 密钥对

在开始之前，您需要拥有一对 SSH 密钥：一个私钥（例如 id_ed25519 或 github_key）和一个公钥（id_ed25519.pub 或 github_key.pub）。

⚠️ 警告: 私钥是您的身份凭证，绝对不能泄露给任何人。请妥善保管。

如果您还没有密钥，可以使用以下命令生成一对新的（推荐使用 Ed25519 算法）：

# -t 指定算法, -C 添加注释(通常是邮箱), -f 指定生成的文件名
ssh-keygen -t ed25519 -C "your_email@example.com" -f ~/.ssh/github_key

---

第二步：在 GitHub 上部署公钥

1. 用记事本或任何文本编辑器打开您的公钥文件（例如 C:\Users\YourUsername\.ssh\github_key.pub）。
2. 完整复制文件中的所有内容。
3. 登录 GitHub，进入 Settings -> SSH and GPG keys。
4. 点击 New SSH key，将复制的公钥内容粘贴到 “Key” 文本框中，并为它取一个可识别的标题（例如 “My Windows Laptop”）。
5. 点击 Add SSH key。

---

第三步：在 Windows 上部署私钥

这是整个流程的核心，也是最容易出错的地方。

3.1 确认并启动 OpenSSH 服务

首先，确保 Windows 自带的 SSH 客户端和代理服务已准备就绪。

1. 检查组件：进入 Windows 设置 > 系统 > 可选功能，在“已安装功能”列表中搜索并确认 “OpenSSH 客户端” 已安装。
2. 启动代理服务：
   • 按 Win + R，输入 services.msc 回车。
   • 找到服务 “OpenSSH Authentication Agent”。
   • 右键点击 -> 属性，将“启动类型”设置为“自动”，并确保服务状态为“正在运行”。

3.2 将私钥添加到 SSH Agent

SSH Agent 是一个在后台管理私钥的程序。将私钥添加到 Agent 是一劳永逸的最佳实践。

1. 以管理员身份打开 PowerShell 或终端。
2. 运行 ssh-add 命令，指向您的私钥文件：

# 将路径替换为您自己的私钥路径
ssh-add C:\Users\YourUsername\.ssh\github_key

如果您的私钥设置了密码，系统会提示您输入。成功后，您会看到 Identity added 的提示。

---

第四步：解决核心问题 - Permission denied 错误

如果您完成了以上步骤，但在项目目录中执行 git clone 时仍然收到 Permission denied (publickey) 或 error in libcrypto 错误，甚至遇到 No such file or directory 这种路径错误，那么根本原因几乎可以肯定是：您的系统上存在多个 SSH 客户端，而 Git 调用了错误的那一个。

4.1 问题根源：SSH 客户端冲突

• Windows 自带 OpenSSH：位于 C:\Windows\System32\OpenSSH\ssh.exe。您通过 ssh-add 命令交互的是这个客户端的 Agent。
• Git for Windows 自带 SSH：位于 C:\Program Files\Git\usr\bin\ssh.exe。默认情况下，Git 会调用这个它自己捆绑的 SSH 客户端，而这个客户端并不知道 Windows OpenSSH Agent 的存在，且其路径中的空格常会导致脚本调用失败。

因此，Git 拿着自己的钥匙去开门，或者连门都没摸到就报错了。

4.2 解决方案：强制 Git 使用正确的 SSH 客户端

我们需要明确告诉 Git：不要用你自己那个带 Bug 的 SSH，去用系统自带的那个。

1. 获取 SSH 的绝对路径

首先，我们需要确保找到的路径是绝对正确的。在 PowerShell 中运行以下命令：

(Get-Command ssh).Source

系统通常会返回：C:\Windows\System32\OpenSSH\ssh.exe

请复制这个路径备用。

2. 配置 Git 全局设置

接下来，我们将这个绝对路径写入 Git 的全局配置中。

注意：为了防止路径中的空格引起解析错误（虽然 System32 路径通常没空格，但养成好习惯很重要），我们在路径外层加了单引号，再被双引号包裹。

请在 PowerShell 中执行：

# 注意：路径要替换为您上一步获取到的实际路径
# 语法说明："'路径'" -> 双引号包裹单引号，单引号包裹路径
git config --global core.sshCommand "'C:\Windows\System32\OpenSSH\ssh.exe'"

3. 验证配置

配置完成后，检查一下是否生效：

git config --global --get core.sshCommand

如果输出为您刚才设置的路径，即说明配置成功。Git 以后都会直接调用这个系统原生的 SSH 程序。

---

第五步：测试连接与使用

现在，所有配置都已完成，让我们来验证一下。

5.1 测试 SSH 连接

在任意目录下打开一个新的终端，运行：

ssh -T git@github.com

如果看到类似下面的欢迎信息，证明您的私钥已成功通过认证：

Hi Lazygui! You've successfully authenticated, but GitHub does not provide shell access.

5.2 克隆您的项目

现在，进入您的项目文件夹，执行 git clone 命令：

cd D:\projects
git clone git@github.com:Lazygui/Dock.git

这一次，Git 将通过正确的 Windows SSH Agent 进行身份验证，顺利完成克隆。

---

附录：使用 SSH config 文件（推荐）

当您拥有多个 SSH 密钥（例如，一个用于 GitHub，一个用于公司的 GitLab）时，使用 config 文件进行管理是最佳实践。

1. 在您的 .ssh 目录（C:\Users\YourUsername\.ssh）下创建一个名为 config 的文件（没有扩展名）。
2. 用编辑器打开并添加以下内容：

# GitHub Account
Host github.com
  HostName github.com
  User git
  # 使用绝对路径以避免歧义
  IdentityFile C:\Users\YourUsername\.ssh\github_key

这个文件会告诉 SSH 客户端，当连接 github.com 时，应该自动使用哪个私钥。