Li Yihan 李溢涵

logo
李溢涵 | Yihan Li
Robotics & Embodied Intelligence

GitHub SSH 密钥配置

2026/04/15
21
0

本文适用于 Linux / macOS 终端环境，目标是为当前电脑配置 SSH 密钥并用于 GitHub。

1. 为什么选 RSA？

虽然 ed25519 更现代、密钥更短，但如果你当前更希望使用兼容性更广、团队更熟悉的方案，RSA 4096 仍是可用且常见的选择。

建议命令：

ssh-keygen -t rsa -b 4096 -C "你的GitHub邮箱"

2. 检查本机是否已有 SSH 密钥

先查看本机已有密钥文件：

ls -al ~/.ssh

常见文件：

  • 私钥：id_rsa

  • 公钥：id_rsa.pub

如果你已经有并且想复用，可直接跳到“第 5 步：添加公钥到 GitHub”。

3. 生成新的 RSA 4096 密钥

执行：

ssh-keygen -t rsa -b 4096 -C "你的GitHub邮箱"

终端会依次提示：

  1. Enter file in which to save the key ...

  • 直接回车：使用默认路径 ~/.ssh/id_rsa

  • 或输入自定义路径（例如 ~/.ssh/id_rsa_github）

  1. Enter passphrase ...

  • 建议设置密码短语（更安全）

  • 若不想设置可直接回车（不推荐）

  1. Enter same passphrase again

  • 再输入一次确认

完成后你会看到 Your identification has been saved in ...。

4. 启动 ssh-agent 并加载私钥

4.1 启动 agent

eval "$(ssh-agent -s)"

4.2 添加私钥

如果使用默认路径：

ssh-add ~/.ssh/id_rsa

如果你使用了自定义路径，请替换成对应文件。

4.3 检查是否添加成功

ssh-add -l

若看到你的 RSA 指纹，说明已成功。

5. 复制公钥并添加到 GitHub

5.1 输出公钥内容

cat ~/.ssh/id_rsa.pub

复制整行内容（通常以 ssh-rsa 开头）。

5.2 在 GitHub 添加

打开 GitHub 网页并进入：

Settings -> SSH and GPG keys -> New SSH key

填写：

  • Title：例如 my-laptop-2026

  • Key：粘贴刚才复制的完整公钥

点击 Add SSH key 保存。

6. 测试与 GitHub 的 SSH 连接

执行：

ssh -T git@github.com

首次连接可能会提示是否信任主机，输入：

yes

成功时会看到类似：

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

7. 把仓库远程地址改为 SSH（如果当前是 HTTPS）

7.1 查看当前远程

git remote -v

7.2 修改为 SSH 地址

git remote set-url origin git@github.com:你的用户名/你的仓库.git

7.3 再次确认

git remote -v

确认 origin 显示为 git@github.com:... 即可。

8. 常见问题排查

问题 1：Permission denied (publickey)

可按顺序检查：

  1. 是否已 ssh-add 私钥

  2. GitHub 是否粘贴了正确公钥（不要粘贴私钥）

  3. 当前仓库远程地址是否为 SSH 而非 HTTPS

  4. 是否存在多个密钥导致匹配错误

问题 2：有多个 GitHub 账号或多个密钥

可以在 ~/.ssh/config 中为不同主机别名配置不同密钥，例如：

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_rsa
  IdentitiesOnly yes

问题 3：每次重启都要重新 ssh-add

这是常见现象。可按你的系统方式配置登录时自动启动 agent 并加载密钥。

9. 安全建议

  1. 私钥（id_rsa）绝对不要上传到任何代码仓库

  2. 建议给私钥设置 passphrase

  3. 若密钥疑似泄露，立即在 GitHub 删除该公钥并重新生成

  4. 定期审查 GitHub 上已添加的 SSH keys

10. 快速命令清单

# 1) 查看已有密钥
ls -al ~/.ssh

# 2) 生成 RSA 4096 密钥
ssh-keygen -t rsa -b 4096 -C "你的GitHub邮箱"

# 3) 启动 agent
 eval "$(ssh-agent -s)"

# 4) 加载私钥
ssh-add ~/.ssh/id_rsa

# 5) 查看公钥
cat ~/.ssh/id_rsa.pub

# 6) 测试 GitHub 连接
ssh -T git@github.com

# 7) 把仓库改成 SSH 地址
git remote set-url origin git@github.com:你的用户名/你的仓库.git