Git SSH 公钥配置指南（GitHub/GitLab/Gitee）

Git SSH 公钥配置指南

在使用 Git 与远程代码托管平台（如 GitHub、GitLab、Gitee）交互时，SSH 公钥认证是一种比 HTTPS 更安全、更便捷的身份验证方式。配置完成后，你无需每次输入用户名和密码即可推送或拉取代码。

本文将带你完成 SSH 公钥的生成、配置与验证全过程，适用于 Windows（含 WSL）、macOS 和 Linux 系统。

---

一、为什么使用 SSH 而不是 HTTPS？

对比项	HTTPS	SSH
认证方式	用户名 + 密码 / Token	公私钥对（无需每次输入）
安全性	中等（密码可能泄露）	高（密钥加密，无明文传输）
使用便捷性	每次操作需输入凭证（除非缓存）	配置一次，永久免密
企业/自动化场景	不友好	极佳（CI/CD、脚本自动化常用）

推荐：日常开发优先使用 SSH 方式！

---

二、检查是否已有 SSH 密钥

首先，查看本地是否已存在 SSH 密钥：

ls -al ~/.ssh 

如果看到如下文件之一，说明已有密钥：

• id_rsa 和 id_rsa.pub（RSA 算法）
• id_ed25519 和 id_ed25519.pub（Ed25519 算法，更安全、更快，推荐使用）
• id_ecdsa 等

注意：.pub 是公钥（可公开），另一个是私钥（绝对不可泄露！）

如果你已有密钥且仍在使用，可跳过生成步骤，直接使用现有公钥。

---

三、生成新的 SSH 密钥（推荐 Ed25519）

1. 打开终端（Terminal / Git Bash / WSL）

2. 执行生成命令

ssh-keygen -t ed25519 -C "[email protected]"

• -t ed25519：指定使用 Ed25519 加密算法（现代、安全、高效）
• -C "[email protected]"：添加注释（通常是你的邮箱，仅作标识用）

如果系统不支持 Ed25519（较老版本 OpenSSH），可改用其他算法。

3. 设置保存路径（默认即可）

系统会提示：

Enter file in which to save the key (/home/you/.ssh/id_ed25519): 

直接按 回车 使用默认路径。

4. 设置密码（Passphrase，可选但推荐）

Enter passphrase (empty for no passphrase): 

• 输入一个强密码（如 MySshKey2026!），可防止私钥被盗后滥用。
• 若用于自动化脚本（如 CI/CD），可留空（不设密码）。
• 设了密码后，首次使用需输入，后续可通过 ssh-agent 缓存。

生成成功后，你会看到类似输出：

Your identification has been saved in /home/you/.ssh/id_ed25519 
Your public key has been saved in /home/you/.ssh/id_ed25519.pub 
The key fingerprint is: SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxx [email protected] 

---

四、启动 ssh-agent 并添加私钥（避免重复输密码）

1. 启动 ssh-agent（Linux/macOS）

eval "$(ssh-agent -s)"

2. 将私钥加入 agent

ssh-add ~/.ssh/id_ed25519 

如果你设置了 Passphrase，此时会要求输入一次。之后在当前会话中无需再输。

Windows 用户（Git Bash）：上述命令同样适用。
WSL 用户：建议在 WSL 中配置，而非 Windows 原生。

---

五、将公钥添加到代码托管平台

1. 复制公钥内容

cat ~/.ssh/id_ed25519.pub 

或者直接复制到剪贴板（macOS/Linux）：

# macOS pbcopy < ~/.ssh/id_ed25519.pub 
# Linux (需安装 xclip) xclip -sel clip < ~/.ssh/id_ed25519.pub 

务必复制 .pub 文件内容，不要复制私钥！

公钥格式示例：

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG... [email protected] 

2. 添加到平台（以 GitHub 为例）

1. 登录 GitHub
2. 点击右上角头像 → Settings
3. 左侧菜单选择 SSH and GPG keys → New SSH key
4. Title 填写设备名称（如 My MacBook Pro）
5. Key type 选择 Authentication Key
6. 将公钥粘贴到 Key 文本框
7. 点击 Add SSH key

其他平台类似：GitLab：Preferences → SSH Keys；Gitee（码云）：设置 → SSH 公钥；Bitbucket：Personal settings → SSH keys

---

六、测试 SSH 连接

GitHub 测试：

ssh -T [email protected] 

成功响应：

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

GitLab 测试：

ssh -T [email protected] 

Gitee 测试：

ssh -T [email protected] 

出现欢迎信息即表示配置成功！

---

七、将 Git 远程地址改为 SSH 格式

如果你之前使用 HTTPS 克隆仓库，需修改远程 URL：

# 查看当前远程地址
git remote -v 
# 修改为 SSH 地址
git remote set-url origin [email protected]:username/repo.git 

SSH 地址格式通常为：

[email protected]:用户名/仓库名.git 

你可以在仓库页面点击 Code → SSH 获取正确地址。

---

八、常见问题排查

问题 1：Permission denied (publickey)

• 原因：公钥未正确添加，或私钥未加载。
• 解决：
  • 确认 ssh-add -l 能看到你的密钥
  • 检查平台是否粘贴了完整的 .pub 内容（无换行、无多余空格）
  • 尝试 ssh -vT [email protected] 查看详细错误日志

问题 2：Agent admitted failure to sign using the key

• 原因：ssh-agent 未正确加载密钥（常见于 Ubuntu）

解决：

ssh-add ~/.ssh/id_ed25519 

问题 3：Cloning into … fatal: Could not read from remote repository

• 检查远程 URL 是否为 SSH 格式（以 git@ 开头）
• 确保你有该仓库的访问权限

---

九、安全建议

1. 私钥绝不上传或分享（包括截图、聊天、网盘）
2. 为私钥设置 强 Passphrase
3. 定期轮换密钥（尤其离职或设备丢失时）
4. 在平台删除不再使用的 SSH 密钥

---

十、结语

通过以上步骤，你已成功配置 SSH 公钥，实现 安全、免密、高效的 Git 操作体验。无论是个人项目还是团队协作，SSH 都是专业开发者的首选。

记住：.ssh 目录权限应为 700，私钥文件权限应为 600，否则 SSH 可能拒绝使用：