GitHub 身份验证方式 PAT 和 SSH 详解

前言

参考官方文档：GitHub 入门文档

第五章·第三部分：Github 身份验证方式 PAT 和 SSH

Github 通过 Git CLI 方式进行管理，常用的身份验证的方式为 PAT 和 SSH，可以单独分别使用，没有相关联系。

一、PAT 简介

1.1 什么是个人访问令牌（PAT）？

**个人访问令牌（Personal Access Token）是 GitHub 提供的一种用于替代密码的安全凭证。**可以把它理解为：一个用于访问 GitHub API、推送代码、克隆仓库的'一次性密码/授权密钥'。

自 2021 年之后：

GitHub 不再允许命令行使用账户密码登录
在 git push、git pull、clone 时必须使用：
✔ 2FA
✔ 个人访问令牌（PAT）
✔ SSH Key
✔ 或 GitHub CLI 登录

1.2 为什么需要 PAT？（关键原因）

✔ 1. 更安全

密码权限太大且不方便管理，PAT 权限可控，可以随时撤销。

✔ 2. 可以设置不同的权限范围

如：

只允许读仓库
允许推送
允许管理 actions
允许删除包

权限越小越安全。

✔ 3. 可以指定过期时间

不会像密码那样无限生效。

✔ 4. 可以随时撤销某个设备或脚本用的 PAT

避免泄露后无法追踪。

1.3 核心用途

替代「密码」，用于**命令行（git 操作）、第三方工具（VS Code、Git 客户端、API 调用）**访问 GitHub。
例如：用 git clone/push/pull 命令操作远程仓库、用 VS Code 直接连接 GitHub 仓库、调用 GitHub API 获取数据。

1.4 适用场景

本地电脑用 git 命令操作 GitHub 仓库（最常用）；
第三方工具（如 PyCharm、Sourcetree）授权访问 GitHub；
开发时调用 GitHub API（如获取仓库列表、提交记录）。

1.5 两种类型的 PAT

GitHub 有两个不同版本：

⭐ 1) Fine-grained personal access tokens（精细化令牌）——推荐使用

当前 GitHub 主推的方式。

特点：

可以精确指定仓库权限（例如只给一个仓库读写权限）
可以设置细粒度操作权限
更安全
默认过期

适合 绝大多数开发者。

⭐ 2) Classic personal access tokens（经典令牌）

旧版，还能用，但不推荐，操作简单，初学者可以尝试。

特点：

权限范围更大（风险高）
无法指定到单仓库
常用于一些旧工具、CI、脚本

⭐ 3) 传统令牌 vs 细粒度令牌：

传统令牌权限范围更宽泛，适合需要跨模块权限（如同时操作仓库和用户信息）的场景；
细粒度令牌权限更精细，适合仅需操作特定仓库或功能的场景。

二、PAT 具体使用

一共分「创建令牌」和「使用令牌」两步。

2.1 创建个人访问令牌

步骤 1：登录 GitHub 网页端

先通过「用户名 + 密码」登录 GitHub（参考上面的教程）。

步骤 2：进入「个人访问令牌」设置页

点击页面右上角的「头像」→ 选择「Settings」（设置）；
在左侧菜单栏下拉，找到「Developer settings」（开发者设置）→ 点击进入；
左侧选择「Personal access tokens」→
- 点击「Fine-grained tokens」（精细化令牌）
- 点击「Tokens (classic)」（经典令牌，初学者优先选这个，简单易操作）；
点击右上角的「Generate new token」（生成新令牌）。
- 「Fine-grained tokens」（精细化令牌）界面
  - 密码以**github_pat_开头，**格式类似于：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
  - **⚠️注意：**令牌仅显示一次，需立即复制保存，后续可在 'Personal access tokens' 列表中管理已生成的令牌。
- 「Tokens (classic)」（经典令牌）界面
  - 密码以 ghp_开头，格式类似于
    - ghp_c45FN6pao2C9nUaZYhspDFeAZNa86O3hOtok
  - **⚠️注意：**令牌仅显示一次，需立即复制保存。

✍️核心配置项说明：

配置项	作用与建议
Note	填写令牌用途说明（如'Git HTTPS 推送认证'），方便后续区分不同令牌的用途。
Expiration	选择令牌有效期（默认 30 天），建议根据场景选择（短期任务选短时效，长期服务选长时效），过期需重新生成。
Select scopes（权限范围）	需勾选对应权限以赋予令牌能力，常见场景配置如下：- Git 推送 / 拉取：勾选 `repo`（私有仓库完全控制）或 `public_repo`（公共仓库控制）；- GitHub Actions 工作流：勾选 `workflow`；- 包管理（如 GitHub Packages）：勾选 `write:packages`、`read:packages` 等；- 用户信息操作：勾选 `user` 下的 `read:user` 等。建议遵循'最小权限原则'，仅勾选必要权限。

✍️核心配置项说明：

配置项	作用与建议
Token name	填写令牌名称（如'前端项目 API 访问令牌'），用于区分不同用途的令牌，建议语义化命名。
Description	选填项，可描述令牌用途（如'用于本地 Git 推送 HTTPS 认证'），方便后续管理。
Resource owner	默认关联你的 GitHub 账号（如 `zhengjingjiaozhu`），确保令牌仅操作你名下的资源。
Expiration	选择令牌有效期（默认 30 天），建议根据使用场景选择（短期任务选短时效，长期服务选长时效），过期后需重新生成。
Repository access	选择仓库访问范围：- Public repositories：仅只读访问公共仓库；- All repositories：访问你所有仓库（含公共和私有）；- Only select repositories：仅访问指定仓库（最多 50 个）。建议遵循'最小权限原则'，按需选择范围。
Permissions	点击「+ Add permissions」可添加细分权限（如仓库的'Read and write'、Issues 的'Read-only'等），需根据实际需求配置（如 Git 推送需仓库的写权限）。

⚠️若未保存，只能重新生成新令牌，旧令牌会失效。

2.2 使用个人访问令牌（实际场景）

场景 1：命令行（git 操作）—— 最常用

例如：克隆 GitHub 仓库、推送代码到远程仓库。

步骤 1：打开本地命令行（git bash/终端 / CMD）

Windows：按 Win+R，输入 cmd 打开命令提示符；
Mac/Linux：打开 Terminal（终端）。

步骤 2：执行 git 命令（以 git clone 为例）

输入克隆命令（从 GitHub 仓库复制的 HTTPS 地址）：

git clone https://github.com/你的用户名/你的仓库名.git

步骤 3：输入凭证验证

命令执行后，会弹出窗口要求输入「用户名」和「密码」：
- 用户名：输入你的 GitHub 用户名；
- 密码：粘贴你刚才生成的 PAT（不是登录密码！）；
点击确认，即可成功克隆仓库。

后续操作（git push/pull）

第一次验证后，系统会自动保存凭证（Windows 保存在凭据管理器，Mac 保存在钥匙串），后续执行 git push、git pull 时无需重复输入。

场景 2：VS Code 中授权访问 GitHub

步骤 1：在 VS Code 中打开「源代码管理」

点击左侧菜单栏的「源代码管理」图标（或按 Ctrl+Shift+G）。

步骤 2：连接 GitHub

点击「克隆仓库」→ 粘贴 GitHub 仓库的 HTTPS 地址；
选择本地保存路径；
弹出凭证窗口时，输入「GitHub 用户名」和「PAT」，即可成功连接。

三、SSH 密钥认证简介

3.1 什么是 SSH 密钥认证？

SSH（Secure Shell）是一种安全加密协议，用于安全登录和数据传输。SSH 密钥认证是一种不需要输入密码的加密登录方式。可以把它理解为：一个用来证明'你就是你'的身份证明文件。

它由两部分组成：

私钥（private key） —— 保存在你的电脑，不可泄露
公钥（public key） —— 上传到 GitHub

只要私钥和公钥匹配，你的电脑就可以'证明身份'，无需密码即可 git push / pull。

3.2 SSH 认证与 HTTPS + PAT 的区别

方式	需要输入密码？	安全性	使用场景
HTTPS + PAT	第一次 push 要输入 Token	高	脚本/工具/CI
SSH 密钥	不需要输入密码（或仅输入一次 passphrase）	非常高	程序员日常开发最推荐

SSH 最大的好处就是：

✔ 可替代「PAT」，push / pull 不用每次输入 Token
✔ 密钥可以长期使用，一次配置，永久免输凭证（无需每次复制 PAT）
✔ 更适合集成开发环境（VSCode / IDEA）

3.3 适用场景

频繁用 git 命令（clone/push/pull）操作 GitHub 仓库（比 PAT 更方便）；
本地工具（VS Code、Git 客户端、PyCharm）连接 GitHub 仓库（支持 SSH 地址的场景）；
追求「免密操作」的高效开发场景。

四、SSH 具体操作

一共分「生成密钥→上传公钥→测试使用」三步。

4.1 生成 SSH 密钥对（本地操作）

步骤 1：打开终端 / 命令行

Windows：git bash/CMD / PowerShell；
Mac/Linux：直接打开 Terminal。

步骤 2：检查本地是否已有 SSH 密钥（避免重复生成）

输入以下命令，查看是否存在密钥文件：

# CMD 方法 1：使用 dir 命令
dir %USERPROFILE%\.ssh
# CMD 方法 2：直接导航到目录
cd %USERPROFILE%\.ssh
dir
# PowerShell 中
Get-ChildItem ~\.ssh
# git bash/Mac/Linux 通用
ls -al ~/.ssh

若输出中包含 id_rsa（私钥）和 id_rsa.pub（公钥），说明已有密钥，可直接跳到「上传公钥」步骤；
若没有，则继续生成新密钥。

步骤 3：生成 SSH 密钥对（关键步骤）

输入以下命令，替换为你的 GitHub 绑定邮箱（用于标识密钥）：

# 使用更安全的 Ed25519 算法
ssh-keygen -t ed25519 -C "[email protected]"
# 或者使用 RSA（如果系统较旧）
ssh-keygen -t rsa -b 4096 -C "[email protected]"

🔖ssh-keygen 命令语法：
- 常用选项说明：
- 密钥类型比较

类型	命令示例	安全性	性能	兼容性	推荐场景
Ed25519	`ssh-keygen -t ed25519 -C "email"`	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	首选，现代系统
ECDSA	`ssh-keygen -t ecdsa -b 256 -C "email"`	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	中等安全需求
RSA	`ssh-keygen -t rsa -b 4096 -C "email"`	⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐	老旧系统兼容

选项	说明
`-t type`	指定密钥类型（如 `ed25519`, `rsa`, `ecdsa`）
`-b bits`	指定密钥长度（位数）
`-C comment`	添加注释，通常用邮箱标识密钥所有者
`-f filename`	指定密钥文件保存路径和名称
`-p`	更改私钥的密码（不更改私钥本身）
`-y`	从私钥生成对应的公钥
`-q`	静默模式，不显示提示信息

执行后会出现三次交互，全部按回车默认即可（无需手动输入）：

「Enter file in which to save the key」：密钥保存路径（默认 ~/.ssh/id_rsa，无需修改）；
「Enter passphrase」：密钥密码（可选，设置后每次使用需输密码，更安全；初学者可直接回车跳过，免输密码）；
「Enter same passphrase again」：重复密码（跳过则直接回车）。

步骤 4：确认密钥生成成功

再次执行「检查密钥」命令

若能看到下面两个文件，说明生成成功：

文件	内容	用途	分享安全性
`id_ed25519`	私钥	保存在本地，绝对保密	🚫 绝不分享
`id_ed25519.pub`	公钥	上传到 GitHub/服务器	✅ 可以安全分享

🔖提示：ssh-keygen 更多命令见附录

4.2 上传公钥到 GitHub（网页端操作）

步骤 1：复制公钥内容（本地终端执行）

🔑方式一：直接查看公钥文件，拷贝密钥

在 C:\Users\当前用户.ssh 下面，用文本编辑器打开公钥文件，拷贝以 ssh 开头的整行字符串，备用

🔑方式二：使用命令查看：

Mac/Linux：

#换成你的公钥文件名
pbcopy < ~/.ssh/yourfilename.pub # 直接复制到剪贴板，无需手动选中

Windows：

cat ~/.ssh/yourfilename.pub #换成你的公钥文件名

执行后，终端会输出一串以 ssh 开头、以你的邮箱结尾的整行字符串（这就是公钥），完整复制这串字符（包括开头的 ssh-rsa 和结尾的邮箱）。

步骤 2：在 GitHub 中添加公钥

登录 GitHub 网页端，点击右上角「头像」→「Settings」；
左侧菜单栏找到「SSH and GPG keys」（SSH 和 GPG 密钥）→ 点击进入；
点击右上角「New SSH key」（新建 SSH 密钥）；
- 「Title」（标题）：自定义名称，方便区分（例如：「我的笔记本电脑」「公司电脑」）；
- 「Key type」（密钥类型）：默认「Authentication key」（认证密钥）；
- 「Key」（密钥内容）：粘贴刚才复制的公钥字符串（确保没有多余空格或换行）；
点击「Add SSH key」（添加 SSH 密钥），若弹出密码验证（输入 GitHub 登录密码），验证后即可添加成功。

4.3 使用 SSH 密钥操作仓库（实际场景）

步骤 1：终端执行测试命令

ssh -T [email protected]

这是 GitHub 官方提供的测试命令，用于验证本地 SSH 能否与 GitHub 服务器正常通信。

✍️提示：

也许首次执行会弹出「是否继续连接」的提示（类似：The authenticity of host 'github.com (xx.xx.xx.xx)' can't be established...）；
直接输入 yes 并回车（无需输入其他内容）。
若终端输出以下内容，说明配置成功：
- Hi 你的 GitHub 用户名! You've successfully authenticated, but GitHub does not provide shell access.
若提示「Permission denied」（权限拒绝），检查公钥是否复制完整、GitHub 中添加的公钥是否正确。

🤔💡可能出现的错误： 检查：一看解析不对，关闭了 Watt Toolkit，结果就正常了。

场景：用 git clone 克隆仓库（SSH 地址）

无需输入用户名 / 密码，直接克隆成功！后续执行 git push git pull 也无需验证，自动通过 SSH 密钥授权。

终端执行克隆命令：

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

打开 GitHub 目标仓库页面，点击「Code」按钮，切换到「SSH」标签，复制 SSH 地址（格式：[email protected]:用户名/仓库名.git）；

4. 注意事项（避免踩坑）

私钥（id_rsa）是核心凭证，绝对不要分享给他人、不要上传到代码仓库（泄露会导致账户被恶意操作）；
一台电脑只需生成一对 SSH 密钥，可用于连接多个 GitHub 仓库（无需重复生成）；
若更换电脑 / 重装系统，需重新生成密钥对并上传新公钥到 GitHub；
若 SSH 连接失败，可执行 ssh -vT [email protected]（加 -v 查看详细日志），排查公钥配置或网络问题。

附录

🔑 ssh-keygen 密钥管理

# 更改密钥密码
ssh-keygen -p -f ~/.ssh/id_ed25519
# 查看密钥指纹
ssh-keygen -l -f ~/.ssh/id_ed25519
# 查看密钥指纹（MD5 格式）
ssh-keygen -l -E md5 -f ~/.ssh/id_ed25519
# 从私钥重新生成公钥
ssh-keygen -y -f ~/.ssh/id_ed25519 > ~/.ssh/id_ed25519.pub

🔍 ssh-keygen 故障排除

1. 检查密钥信息

# 检查密钥指纹
ssh-keygen -l -f ~/.ssh/id_ed25519
# 检查密钥类型和长度
ssh-keygen -l -f ~/.ssh/id_ed25519 | awk '{print $4, $5}'
# 验证密钥格式
ssh-keygen -e -f ~/.ssh/id_ed25519.pub

2. 测试连接

# 测试 SSH 连接到 GitHub
ssh -T [email protected]
# 使用特定密钥测试
ssh -T -i ~/.ssh/github [email protected]
# 详细模式查看连接过程
ssh -T -v [email protected]

3. 常见错误解决

# 错误：Permissions are too open
chmod 600 ~/.ssh/your_private_key
# 错误：Key format not supported
# 重新生成密钥或转换格式
ssh-keygen -p -m PEM -f ~/.ssh/old_key
# 错误：No such file or directory
# 检查文件路径和名称
ls -la ~/.ssh/

前言

参考官方文档：GitHub 入门文档

第五章·第三部分：Github 身份验证方式 PAT 和 SSH

Github 通过 Git CLI 方式进行管理，常用的身份验证的方式为 PAT 和 SSH，可以单独分别使用，没有相关联系。

一、PAT 简介

1.1 什么是个人访问令牌（PAT）？

自 2021 年之后：

GitHub 不再允许命令行使用账户密码登录
在 git push、git pull、clone 时必须使用：
✔ 2FA
✔ 个人访问令牌（PAT）
✔ SSH Key
✔ 或 GitHub CLI 登录

1.2 为什么需要 PAT？（关键原因）

✔ 1. 更安全

密码权限太大且不方便管理，PAT 权限可控，可以随时撤销。

✔ 2. 可以设置不同的权限范围

如：

只允许读仓库
允许推送
允许管理 actions
允许删除包

权限越小越安全。

✔ 3. 可以指定过期时间

不会像密码那样无限生效。

✔ 4. 可以随时撤销某个设备或脚本用的 PAT

避免泄露后无法追踪。

1.3 核心用途

替代「密码」，用于**命令行（git 操作）、第三方工具（VS Code、Git 客户端、API 调用）**访问 GitHub。
例如：用 git clone/push/pull 命令操作远程仓库、用 VS Code 直接连接 GitHub 仓库、调用 GitHub API 获取数据。

1.4 适用场景

本地电脑用 git 命令操作 GitHub 仓库（最常用）；
第三方工具（如 PyCharm、Sourcetree）授权访问 GitHub；
开发时调用 GitHub API（如获取仓库列表、提交记录）。

1.5 两种类型的 PAT

GitHub 有两个不同版本：

⭐ 1) Fine-grained personal access tokens（精细化令牌）——推荐使用

当前 GitHub 主推的方式。

特点：

可以精确指定仓库权限（例如只给一个仓库读写权限）
可以设置细粒度操作权限
更安全
默认过期

适合 绝大多数开发者。

⭐ 2) Classic personal access tokens（经典令牌）

旧版，还能用，但不推荐，操作简单，初学者可以尝试。

特点：

权限范围更大（风险高）
无法指定到单仓库
常用于一些旧工具、CI、脚本

⭐ 3) 传统令牌 vs 细粒度令牌：

传统令牌权限范围更宽泛，适合需要跨模块权限（如同时操作仓库和用户信息）的场景；
细粒度令牌权限更精细，适合仅需操作特定仓库或功能的场景。

二、PAT 具体使用

一共分「创建令牌」和「使用令牌」两步。

2.1 创建个人访问令牌

步骤 1：登录 GitHub 网页端

先通过「用户名 + 密码」登录 GitHub（参考上面的教程）。

步骤 2：进入「个人访问令牌」设置页

点击页面右上角的「头像」→ 选择「Settings」（设置）；
在左侧菜单栏下拉，找到「Developer settings」（开发者设置）→ 点击进入；
左侧选择「Personal access tokens」→
- 点击「Fine-grained tokens」（精细化令牌）
- 点击「Tokens (classic)」（经典令牌，初学者优先选这个，简单易操作）；
点击右上角的「Generate new token」（生成新令牌）。
- 「Fine-grained tokens」（精细化令牌）界面
  - 密码以**github_pat_开头，**格式类似于：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
  - **⚠️注意：**令牌仅显示一次，需立即复制保存，后续可在 'Personal access tokens' 列表中管理已生成的令牌。
- 「Tokens (classic)」（经典令牌）界面
  - 密码以 ghp_开头，格式类似于
    - ghp_c45FN6pao2C9nUaZYhspDFeAZNa86O3hOtok
  - **⚠️注意：**令牌仅显示一次，需立即复制保存。

✍️核心配置项说明：

配置项	作用与建议
Note	填写令牌用途说明（如'Git HTTPS 推送认证'），方便后续区分不同令牌的用途。
Expiration	选择令牌有效期（默认 30 天），建议根据场景选择（短期任务选短时效，长期服务选长时效），过期需重新生成。
Select scopes（权限范围）	需勾选对应权限以赋予令牌能力，常见场景配置如下：- Git 推送 / 拉取：勾选 `repo`（私有仓库完全控制）或 `public_repo`（公共仓库控制）；- GitHub Actions 工作流：勾选 `workflow`；- 包管理（如 GitHub Packages）：勾选 `write:packages`、`read:packages` 等；- 用户信息操作：勾选 `user` 下的 `read:user` 等。建议遵循'最小权限原则'，仅勾选必要权限。

✍️核心配置项说明：

配置项	作用与建议
Token name	填写令牌名称（如'前端项目 API 访问令牌'），用于区分不同用途的令牌，建议语义化命名。
Description	选填项，可描述令牌用途（如'用于本地 Git 推送 HTTPS 认证'），方便后续管理。
Resource owner	默认关联你的 GitHub 账号（如 `zhengjingjiaozhu`），确保令牌仅操作你名下的资源。
Expiration	选择令牌有效期（默认 30 天），建议根据使用场景选择（短期任务选短时效，长期服务选长时效），过期后需重新生成。
Repository access	选择仓库访问范围：- Public repositories：仅只读访问公共仓库；- All repositories：访问你所有仓库（含公共和私有）；- Only select repositories：仅访问指定仓库（最多 50 个）。建议遵循'最小权限原则'，按需选择范围。
Permissions	点击「+ Add permissions」可添加细分权限（如仓库的'Read and write'、Issues 的'Read-only'等），需根据实际需求配置（如 Git 推送需仓库的写权限）。

⚠️若未保存，只能重新生成新令牌，旧令牌会失效。

2.2 使用个人访问令牌（实际场景）

场景 1：命令行（git 操作）—— 最常用

例如：克隆 GitHub 仓库、推送代码到远程仓库。

步骤 1：打开本地命令行（git bash/终端 / CMD）

Windows：按 Win+R，输入 cmd 打开命令提示符；
Mac/Linux：打开 Terminal（终端）。

步骤 2：执行 git 命令（以 git clone 为例）

输入克隆命令（从 GitHub 仓库复制的 HTTPS 地址）：

git clone https://github.com/你的用户名/你的仓库名.git

步骤 3：输入凭证验证

命令执行后，会弹出窗口要求输入「用户名」和「密码」：
- 用户名：输入你的 GitHub 用户名；
- 密码：粘贴你刚才生成的 PAT（不是登录密码！）；
点击确认，即可成功克隆仓库。

后续操作（git push/pull）

第一次验证后，系统会自动保存凭证（Windows 保存在凭据管理器，Mac 保存在钥匙串），后续执行 git push、git pull 时无需重复输入。

场景 2：VS Code 中授权访问 GitHub

步骤 1：在 VS Code 中打开「源代码管理」

点击左侧菜单栏的「源代码管理」图标（或按 Ctrl+Shift+G）。

步骤 2：连接 GitHub

点击「克隆仓库」→ 粘贴 GitHub 仓库的 HTTPS 地址；
选择本地保存路径；
弹出凭证窗口时，输入「GitHub 用户名」和「PAT」，即可成功连接。

三、SSH 密钥认证简介

3.1 什么是 SSH 密钥认证？

它由两部分组成：

私钥（private key） —— 保存在你的电脑，不可泄露
公钥（public key） —— 上传到 GitHub

只要私钥和公钥匹配，你的电脑就可以'证明身份'，无需密码即可 git push / pull。

3.2 SSH 认证与 HTTPS + PAT 的区别

方式	需要输入密码？	安全性	使用场景
HTTPS + PAT	第一次 push 要输入 Token	高	脚本/工具/CI
SSH 密钥	不需要输入密码（或仅输入一次 passphrase）	非常高	程序员日常开发最推荐

SSH 最大的好处就是：

3.3 适用场景

频繁用 git 命令（clone/push/pull）操作 GitHub 仓库（比 PAT 更方便）；
本地工具（VS Code、Git 客户端、PyCharm）连接 GitHub 仓库（支持 SSH 地址的场景）；
追求「免密操作」的高效开发场景。

四、SSH 具体操作

一共分「生成密钥→上传公钥→测试使用」三步。

4.1 生成 SSH 密钥对（本地操作）

步骤 1：打开终端 / 命令行

Windows：git bash/CMD / PowerShell；
Mac/Linux：直接打开 Terminal。

步骤 2：检查本地是否已有 SSH 密钥（避免重复生成）

输入以下命令，查看是否存在密钥文件：

# CMD 方法 1：使用 dir 命令
dir %USERPROFILE%\.ssh
# CMD 方法 2：直接导航到目录
cd %USERPROFILE%\.ssh
dir
# PowerShell 中
Get-ChildItem ~\.ssh
# git bash/Mac/Linux 通用
ls -al ~/.ssh

若输出中包含 id_rsa（私钥）和 id_rsa.pub（公钥），说明已有密钥，可直接跳到「上传公钥」步骤；
若没有，则继续生成新密钥。

步骤 3：生成 SSH 密钥对（关键步骤）

输入以下命令，替换为你的 GitHub 绑定邮箱（用于标识密钥）：

# 使用更安全的 Ed25519 算法
ssh-keygen -t ed25519 -C "[email protected]"
# 或者使用 RSA（如果系统较旧）
ssh-keygen -t rsa -b 4096 -C "[email protected]"

🔖ssh-keygen 命令语法：
- 常用选项说明：
- 密钥类型比较

类型	命令示例	安全性	性能	兼容性	推荐场景
Ed25519	`ssh-keygen -t ed25519 -C "email"`	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	首选，现代系统
ECDSA	`ssh-keygen -t ecdsa -b 256 -C "email"`	⭐⭐⭐⭐	⭐⭐⭐⭐	⭐⭐⭐	中等安全需求
RSA	`ssh-keygen -t rsa -b 4096 -C "email"`	⭐⭐⭐	⭐⭐	⭐⭐⭐⭐⭐	老旧系统兼容

选项	说明
`-t type`	指定密钥类型（如 `ed25519`, `rsa`, `ecdsa`）
`-b bits`	指定密钥长度（位数）
`-C comment`	添加注释，通常用邮箱标识密钥所有者
`-f filename`	指定密钥文件保存路径和名称
`-p`	更改私钥的密码（不更改私钥本身）
`-y`	从私钥生成对应的公钥
`-q`	静默模式，不显示提示信息

执行后会出现三次交互，全部按回车默认即可（无需手动输入）：

「Enter file in which to save the key」：密钥保存路径（默认 ~/.ssh/id_rsa，无需修改）；
「Enter passphrase」：密钥密码（可选，设置后每次使用需输密码，更安全；初学者可直接回车跳过，免输密码）；
「Enter same passphrase again」：重复密码（跳过则直接回车）。

步骤 4：确认密钥生成成功

再次执行「检查密钥」命令

若能看到下面两个文件，说明生成成功：

文件	内容	用途	分享安全性
`id_ed25519`	私钥	保存在本地，绝对保密	🚫 绝不分享
`id_ed25519.pub`	公钥	上传到 GitHub/服务器	✅ 可以安全分享

🔖提示：ssh-keygen 更多命令见附录

4.2 上传公钥到 GitHub（网页端操作）

步骤 1：复制公钥内容（本地终端执行）

🔑方式一：直接查看公钥文件，拷贝密钥

在 C:\Users\当前用户.ssh 下面，用文本编辑器打开公钥文件，拷贝以 ssh 开头的整行字符串，备用

🔑方式二：使用命令查看：

Mac/Linux：

#换成你的公钥文件名
pbcopy < ~/.ssh/yourfilename.pub # 直接复制到剪贴板，无需手动选中

Windows：

cat ~/.ssh/yourfilename.pub #换成你的公钥文件名

执行后，终端会输出一串以 ssh 开头、以你的邮箱结尾的整行字符串（这就是公钥），完整复制这串字符（包括开头的 ssh-rsa 和结尾的邮箱）。

步骤 2：在 GitHub 中添加公钥

登录 GitHub 网页端，点击右上角「头像」→「Settings」；
左侧菜单栏找到「SSH and GPG keys」（SSH 和 GPG 密钥）→ 点击进入；
点击右上角「New SSH key」（新建 SSH 密钥）；
- 「Title」（标题）：自定义名称，方便区分（例如：「我的笔记本电脑」「公司电脑」）；
- 「Key type」（密钥类型）：默认「Authentication key」（认证密钥）；
- 「Key」（密钥内容）：粘贴刚才复制的公钥字符串（确保没有多余空格或换行）；
点击「Add SSH key」（添加 SSH 密钥），若弹出密码验证（输入 GitHub 登录密码），验证后即可添加成功。

4.3 使用 SSH 密钥操作仓库（实际场景）

步骤 1：终端执行测试命令

ssh -T [email protected]

这是 GitHub 官方提供的测试命令，用于验证本地 SSH 能否与 GitHub 服务器正常通信。

✍️提示：

也许首次执行会弹出「是否继续连接」的提示（类似：The authenticity of host 'github.com (xx.xx.xx.xx)' can't be established...）；
直接输入 yes 并回车（无需输入其他内容）。
若终端输出以下内容，说明配置成功：
- Hi 你的 GitHub 用户名! You've successfully authenticated, but GitHub does not provide shell access.
若提示「Permission denied」（权限拒绝），检查公钥是否复制完整、GitHub 中添加的公钥是否正确。

🤔💡可能出现的错误： 检查：一看解析不对，关闭了 Watt Toolkit，结果就正常了。

场景：用 git clone 克隆仓库（SSH 地址）

无需输入用户名 / 密码，直接克隆成功！后续执行 git push git pull 也无需验证，自动通过 SSH 密钥授权。

终端执行克隆命令：

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

打开 GitHub 目标仓库页面，点击「Code」按钮，切换到「SSH」标签，复制 SSH 地址（格式：[email protected]:用户名/仓库名.git）；

4. 注意事项（避免踩坑）

私钥（id_rsa）是核心凭证，绝对不要分享给他人、不要上传到代码仓库（泄露会导致账户被恶意操作）；
一台电脑只需生成一对 SSH 密钥，可用于连接多个 GitHub 仓库（无需重复生成）；
若更换电脑 / 重装系统，需重新生成密钥对并上传新公钥到 GitHub；
若 SSH 连接失败，可执行 ssh -vT [email protected]（加 -v 查看详细日志），排查公钥配置或网络问题。

附录

🔑 ssh-keygen 密钥管理

# 更改密钥密码
ssh-keygen -p -f ~/.ssh/id_ed25519
# 查看密钥指纹
ssh-keygen -l -f ~/.ssh/id_ed25519
# 查看密钥指纹（MD5 格式）
ssh-keygen -l -E md5 -f ~/.ssh/id_ed25519
# 从私钥重新生成公钥
ssh-keygen -y -f ~/.ssh/id_ed25519 > ~/.ssh/id_ed25519.pub

🔍 ssh-keygen 故障排除

1. 检查密钥信息

# 检查密钥指纹
ssh-keygen -l -f ~/.ssh/id_ed25519
# 检查密钥类型和长度
ssh-keygen -l -f ~/.ssh/id_ed25519 | awk '{print $4, $5}'
# 验证密钥格式
ssh-keygen -e -f ~/.ssh/id_ed25519.pub

2. 测试连接

# 测试 SSH 连接到 GitHub
ssh -T [email protected]
# 使用特定密钥测试
ssh -T -i ~/.ssh/github [email protected]
# 详细模式查看连接过程
ssh -T -v [email protected]

3. 常见错误解决

# 错误：Permissions are too open
chmod 600 ~/.ssh/your_private_key
# 错误：Key format not supported
# 重新生成密钥或转换格式
ssh-keygen -p -m PEM -f ~/.ssh/old_key
# 错误：No such file or directory
# 检查文件路径和名称
ls -la ~/.ssh/