Git SSH 连接配置 · 速览

为什么要配置 SSH？

HTTPS 方式每次推送/拉取都要输入账号密码（或 Token）；SSH 通过密钥对认证，一次配置、长期免密。一台电脑还可以配置多把密钥，对应多个 GitHub 账号（如个人号 + 工作号）。

整体流程

生成密钥对 → GitHub 配置公钥 → 本地配置配对规则 → 测试连接

第一步：生成密钥对

⚠️ Windows 的坑（~ 不展开）：PowerShell 和 cmd 都不会把 ~ 展开为用户目录，Windows 版 ssh-keygen 自己也不认识 ~——直接照抄命令会报错 Saving key "~/.ssh/xxx" failed: No such file or directory（它把 ~/.ssh 当成了当前目录下的普通文件夹）。

正确姿势（任选其一）：

• 在 Git Bash 里执行原命令（bash 会自动展开 ~）
• 在 PowerShell 里把 ~ 换成 $HOME：-f $HOME/.ssh/xxx_github_key

Mac 无此问题。

ssh-keygen -t ed25519 -C "注册github的邮箱地址" -f ~/.ssh/xxx_github_key

参数说明：

参数	含义
-t ed25519	密钥算法，ed25519 是当前推荐的现代安全算法
-C "邮箱"	备注信息，建议填注册 GitHub 的邮箱
-f 路径	指定密钥的保存路径和文件名

命令执行后的一系列交互（是否设置密码等）一路回车保持默认即可。

生成完成后，~/.ssh 目录下会出现两个文件（Windows 位置：C:/Users/你的用户名/.ssh）：

文件	是什么	能否公开
xxx_github_key	私钥	❌ 绝不外传
xxx_github_key.pub	公钥	✅ 上传到 GitHub

第二步：GitHub 配置公钥

1. 打开 https://github.com/settings/keys
2. 点击 New SSH key
3. Title 随意填（如"我的电脑"），Key 粘贴公钥内容
4. 点击 Add SSH key 完成

查看公钥内容：

cat ~/.ssh/xxx_github_key.pub                              # Mac / Linux
type C:\Users\你的用户名\.ssh\xxx_github_key.pub            # Windows PowerShell

第三步：配置密钥配对规则

只用一个账号可以跳过这一步；多个账号（个人 + 工作）必须配置，让连接不同仓库时自动使用对应的密钥。

1. 打开 ~/.ssh/config 文件（没有就新建一个）

2. 写入配对规则：

   # 规则示例
   Host gmail.github.com                    # 别名：连接 git@gmail.github.com 时匹配此规则
     HostName github.com                    # 实际连接的服务器
     IdentityFile ~/.ssh/gmail_github_key   # 使用的私钥
     User git                               # 固定写法
   

3. 测试连接：

   ssh -T git@你配置的别名        # 如：ssh -T git@gmail.github.com
   

   成功的结果是：

   Hi xxx! You've successfully authenticated ...
   

多账号实战

个人号 + 工作号的典型配置：

# 个人账号
Host personal.github.com
  HostName github.com
  IdentityFile ~/.ssh/personal_github_key
  User git

# 工作账号
Host work.github.com
  HostName github.com
  IdentityFile ~/.ssh/work_github_key
  User git

config 文件里可以放心写 ~，OpenSSH 自己会展开（不像命令行参数那样原样传给外部程序）。当本机密钥很多（超过 5 把）时，连接会一把把试过去，超出服务器认证次数限制报 Too many authentication failures——在对应规则里加一行 IdentitiesOnly yes，只使用指定的那把钥匙即可。

克隆 / 添加远程仓库时，把地址里的主机名换成对应的别名：

git clone git@personal.github.com:用户名/仓库名.git   # 走个人密钥
git clone git@work.github.com:公司名/仓库名.git       # 走工作密钥

常见问题

生成密钥报 Saving key "~/.ssh/xxx" failed: No such file or directory

Windows 下 ~ 没有被展开（见上文第一步的坑），处理方式二选一：

• 换成 Git Bash 执行原命令
• 或把 -f 后面的 ~ 改成 $HOME（PowerShell）

若报错里显示的是完整路径（如 Saving key "C:\Users\xxx\.ssh\..." failed），说明是 ~/.ssh 目录还不存在，先建目录再重试：

New-Item -ItemType Directory -Force "$HOME\.ssh"

测试连接报 Permission denied

按顺序排查：

1. 公钥是否真的添加到 GitHub 了（Settings → SSH and GPG keys）
2. IdentityFile 路径是否写对（注意 ~ 代表用户主目录）
3. 私钥文件名是否与生成时一致
4. 测试命令里跟的别名是否与 Host 配置一致

配置好了还提示输入密码

说明 SSH 没生效，仓库可能还在使用 HTTPS 地址。查看并修改远程地址：

git remote -v                              # 确认当前是 https:// 还是 git@ 开头
git remote set-url origin git@gmail.github.com:用户名/仓库名.git

要点回顾

1. 私钥留在本地、绝不外传；公钥上传 GitHub
2. Windows 命令行中 ~ 不展开：用 Git Bash，或在 PowerShell 里写 $HOME
3. Host 只是别名，真正的服务器写在 HostName
4. 测试命令 ssh -T 后面跟的是别名，不是 github.com
5. 配置完成后仓库地址要用 git@别名:... 格式，SSH 才会生效