ostone's blog

技术 1928 字 5 分钟

GitHub SSH 推送指南

目录
  1. 一、先搞清楚两个概念：Git 和 GitHub
  2. 二、问题是怎么出现的
  3. 三、解决方案：两种认证方式
  4. 表一 · 解决方案：两种认证方式
  5. SSH 密钥是什么
  6. 四、实际操作：一步一步来
  7. 第 1 步：检查电脑上有没有现成的密钥
  8. 第 2 步：查看已有的 config 文件
  9. 第 3 步：确认旧密钥属于哪个账号（可选）
  10. 第 4 步：为账号生成一把全新的密钥
  11. 第 5 步：把公钥添加到 GitHub
  12. 第 6 步：配置别名，告诉 Git 用哪把钥匙
  13. 第 7 步：测试连接
  14. 第 8 步：把仓库地址从 HTTPS 改为 SSH
  15. 第 9 步：保护你的邮箱隐私
  16. 第 10 步：推送
  17. 五、关于多账号的几点总结
  18. 六、让 AI 工具代你提交，会不会卡在鉴权
  19. 七、常见问题速查
  20. 表二 · 常见问题速查
  21. 结语

适合人群：已有github账号，会建仓库，会用或听说过 Git，但对 GitHub 的账号认证、多账号管理不熟的人。

一、先搞清楚两个概念：Git 和 GitHub

Git 是装在你电脑上的版本管理工具，负责记录文件的每一次修改。没有网络它也能用。

GitHub 是一个网站，用来托管 Git 仓库，相当于把你的项目存一份在云端，方便备份、协作和分享。

两者之间需要一个”连接”：你在本地改好代码，要推送（push）到 GitHub。这时 GitHub 必须确认一件事：你是谁，你有没有权限往这个仓库里写东西。 这一步就叫鉴权，很多人卡住的地方就是它。

二、问题是怎么出现的

推送时可能会看到这样的报错：

remote: Invalid username or token. Password authentication is not supported for Git operations.
fatal: Authentication failed for 'https://github.com/yourname/yourrepo.git/'

意思是：GitHub 拒绝了你的身份验证。自 2021 年 8 月起，GitHub 不再支持用账号密码做 Git 操作，你输入的密码无论对错都不会被接受。

常见的原因有两个：

  • 你输入的是登录密码，而不是 token（令牌）。
  • 系统里缓存了旧的或另一个账号的凭据，Git 一直拿错的去认证。

三、解决方案：两种认证方式

方式地址格式认证原理特点
HTTPS + tokenhttps://github.com/...每次用用户名 + token 验证token 会过期，多账号时凭据容易互相覆盖
SSH 密钥git@github.com:...用一对密钥自动验证配置一次，长期免输入

如果你有多个 GitHub 账号，或者想让 AI 工具替你自动提交，SSH 更省心。

SSH 密钥是什么

可以把它想象成一把锁和一把钥匙：

  • 私钥留在你自己的电脑上，绝不外传，相当于钥匙。
  • 公钥交给 GitHub，相当于锁。

推送时，GitHub 用公钥出一道”题”，你的电脑用私钥来解。能解开，就证明你是这把钥匙的主人，全程不需要传输密码。

四、实际操作：一步一步来

第 1 步：检查电脑上有没有现成的密钥

ls ~/.ssh

为什么这样做：先看清现状，避免覆盖已有的密钥。如果看到 id_ed25519 和 id_ed25519.pub，说明你曾经生成过默认密钥。

第 2 步：查看已有的 config 文件

cat ~/.ssh/config

为什么这样做：config 文件决定了”连接某个地址时用哪把密钥”。先看里面有什么，之后追加内容时才不会冲突。里面可能有别的工具自动加的内容，不用动它。

第 3 步：确认旧密钥属于哪个账号（可选）

ssh -T git@github.com

这条命令是在问 GitHub：“我是谁？”

  • 返回 Hi 用户名!：这把密钥已经绑定了某个账号。
  • 返回 Permission denied (publickey)：这把密钥没有绑定任何账号，GitHub 不认识它。

首次连接时会问你是否信任 github.com，输入 yes 即可。这是 SSH 在核对服务器指纹，防止你连到冒牌服务器。

第 4 步：为账号生成一把全新的密钥

ssh-keygen -t ed25519 -C "你的邮箱" -f ~/.ssh/id_ed25519_yourname

各部分的含义：

  • -t ed25519：使用 ed25519 算法，目前推荐的新一代算法，安全且速度快。
  • -C "邮箱"：只是密钥文件里的一条备注，方便你以后辨认，不会出现在提交记录里。
  • -f ~/.ssh/id_ed25519_yourname：指定文件名。

为什么要指定文件名：不指定的话，默认会生成 id_ed25519，如果之前有同名文件就会被覆盖。给每个账号的密钥起不同的名字，是多账号管理的基础。

过程中会问 passphrase（密钥的二次密码），可以直接回车跳过。设了会更安全，但每次使用可能要输入（macOS 钥匙串可以帮你记住）。

生成后你会得到两个文件：

  • id_ed25519_yourname：私钥，不要给任何人。
  • id_ed25519_yourname.pub：公钥，可以公开，要交给 GitHub。

第 5 步：把公钥添加到 GitHub

macOS 上先把公钥复制到剪贴板：

pbcopy < ~/.ssh/id_ed25519_yourname.pub

然后：

  1. 登录要使用的那个 GitHub 账号（确认右上角头像对不对，别登错账号）。
  2. 打开 https://github.com/settings/keys
  3. 点 New SSH key，Title 随便起，Key 栏粘贴，保存。

为什么要这样做：这一步就是把”锁”交给 GitHub。公钥添加到哪个账号，这把钥匙就只能开哪个账号的门。

第 6 步：配置别名，告诉 Git 用哪把钥匙

用文本编辑器打开配置文件：

nano ~/.ssh/config

在文件末尾空一行，加入：

Host yourname
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_yourname
  IdentitiesOnly yes
  AddKeysToAgent yes
  UseKeychain yes

保存方法：按 control + O，回车确认文件名，再按 control + X 退出。

各行的含义：

  • Host yourname：别名，名字随便起，之后连接时用它。
  • HostName github.com：别名实际指向的真实服务器。
  • User git：GitHub 的 SSH 固定用户名就是 git，不是你的账号名。
  • IdentityFile：这个别名使用哪把私钥。
  • IdentitiesOnly yes：只用上面指定的这把钥匙，不要把电脑上其他密钥都试一遍。多账号时这行至关重要，否则可能用错账号。
  • AddKeysToAgent / UseKeychain：让 macOS 记住密钥，不用反复输入 passphrase。

为什么要用别名：两个账号的真实服务器都是 github.com，系统分不清该用哪把密钥。给每个账号起一个别名，别名指向同一个服务器，但各自绑定不同的钥匙，这样就能分开了。

第 7 步：测试连接

ssh -T git@yourname

成功的话会看到：

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

不要被后半句吓到。它的意思是”认证成功了，只是 GitHub 不提供命令行登录服务器的功能”，这是正常的成功提示。

第 8 步：把仓库地址从 HTTPS 改为 SSH

先进入项目文件夹（在终端输入 cd 加空格，再把文件夹从 Finder 拖进终端）。查看当前的远程地址：

git remote -v

如果显示的是 https://github.com/...，说明还在走 HTTPS，这就是之前报错的根源。改成 SSH：

git remote set-url origin git@yourname:yourname/yourrepo.git

这里有两个 yourname，含义不同：

  • git@yourname: 里的是 SSH 别名，对应 config 里的 Host。
  • :yourname/yourrepo.git 里的是 GitHub 用户名 / 仓库名。

为什么要改这一步：前面所有配置都是”准备好钥匙”，而这一步是”让项目改用这把钥匙开门”。不改的话，项目仍然走 HTTPS，一切白做。

再用 git remote -v 检查，确认显示的是 git@yourname:... 即可。

第 9 步：保护你的邮箱隐私

每次 Git 提交都会记录署名邮箱。公开仓库里，任何人都能看到这个邮箱。

GitHub 提供了隐私邮箱：

  1. 打开 https://github.com/settings/emails
  2. 勾选 Keep my email addresses private
  3. 勾选 Block command line pushes that expose my email（如果不小心用真实邮箱提交，GitHub 会拒绝推送）
  4. 页面上会显示一个 noreply 邮箱，格式类似 12345678+yourname@users.noreply.github.com

然后在项目目录里设置署名（不加 --global，只对当前项目生效）：

git config user.name "yourname"
git config user.email "12345678+yourname@users.noreply.github.com"

为什么不能干脆不写邮箱：Git 要求每次提交必须有邮箱字段。而这个 noreply 邮箱是有效的，GitHub 能把提交关联到你的账号，头像和贡献记录都正常显示，同时不暴露真实邮箱。

注意：这只对之后的新提交有效，已经提交过的历史记录里的邮箱不会自动变。

第 10 步：推送

git branch
git push -u origin main

git branch 里带 * 的是当前分支名（main 或 master），推送时用实际的分支名。成功后，你的代码就出现在 GitHub 上了。

五、关于多账号的几点总结

  • 每个账号一把独立的密钥，一个独立的别名。 以后要用第二个账号，重复第 4～6 步，换个文件名和别名即可。
  • 每个项目的远程地址用对应账号的别名。 项目属于哪个账号，就用哪个别名。
  • 提交署名按项目设置。 不同账号的项目，各自设置各自的用户名和邮箱，不要用 --global。

六、让 AI 工具代你提交，会不会卡在鉴权

只要满足下面两点，基本不会：

  • AI 工具运行在你自己的电脑上（例如在本机终端里运行的编程助手），这样它能直接读取你的 ~/.ssh/config 和密钥。
  • 项目的远程地址是 SSH 格式。

如果 AI 运行在云端沙盒里，它访问不到你电脑上的密钥，仍然会认证失败。

七、常见问题速查

现象可能原因处理
Password authentication is not supported用了 HTTPS 并输入了密码改用 SSH 或 token
Permission denied (publickey)公钥没添加到 GitHub，或用错了密钥检查公钥是否添加到正确账号、config 是否正确
用错了账号推送钥匙串缓存了别的凭据，或别名用错检查 git remote -v 里的别名
Host key verification failed服务器指纹不匹配确认网络环境，核对 GitHub 官方公布的指纹

结语

整件事可以浓缩成一句话：生成一对密钥，把公钥交给 GitHub，用别名告诉 Git 该用哪把钥匙，再让项目改走 SSH 地址。 每一步都只是在回答同一个问题：GitHub 怎么确认”你就是你”。理解了这一点，以后遇到任何鉴权报错，都能沿着这条线索排查。