文档目录导航（当前：GitHub SSH 密钥配置与 Personal Access Token (PAT) 认证指南）
入门指南
快速上手总览
核心服务
GitHub 加速下载代理使用指南 Docker 镜像加速配置全指南 SourceForge 加速下载代理使用指南 OpenSheet - Google 表格转 JSON 接口文档
客户端配置
Git 客户端全局配置
GitHub 实战教程
GitHub SSH 密钥配置与 Personal Access Token (PAT) 认证指南 GitHub Flow 协作全流程：从 Fork 到发起 Pull Request (PR) GitHub Actions 自动化 CI/CD 快速入门与实战 GitHub Pages 免费搭建个人博客与项目文档指南 Git Submodule 子模块加速克隆与常见网络报错排查
平台说明
关于网站广告与持续运营说明
文章目录导航12节

GitHub SSH 密钥配置与 Personal Access Token (PAT) 认证指南

在使用 Git 向 GitHub 提交代码或拉取私有仓库时，身份鉴权是必经的第一步。

自 2021 年 8 月起，GitHub 已全面移除对账户密码直接进行 Git 操作的支持（若使用密码会收到 remote: Support for password authentication was removed on August 13, 2021. 错误）。目前官方推荐的两大主流认证方式为：SSH 密钥认证 与 Personal Access Token (PAT 个人访问令牌)。

本教程将手把手带你完成两种认证方式的配置与日常故障排查。

一、SSH 密钥认证全流程配置

SSH（Secure Shell）通过非对称加密算法进行身份识别。本地保留私钥，公钥上传到 GitHub，每次 git clone [email protected]:... 或 git push 时均无需重复输入密码，安全且高效。

1. 检查本地是否已有 SSH 密钥

在终端（Linux/macOS 的 Terminal，或 Windows 的 Git Bash / PowerShell）中执行：

ls -la ~/.ssh

如果输出中已有形如 id_ed25519.pub 或 id_rsa.pub 的文件，说明已经生成过密钥，可直接跳至步骤 3；如果提示目录不存在或没有任何 .pub 结尾的文件，请继续步骤 2。

2. 生成全新的 SSH 密钥对

推荐算法：优先推荐现代高安全性且运算更快的 Ed25519 算法；若所处老旧系统不支持，可退选 RSA 4096 算法。

执行以下命令生成密钥（将邮箱替换为你的 GitHub 注册邮箱）：

# 推荐：生成 Ed25519 密钥
ssh-keygen -t ed25519 -C "[email protected]"

# 备选：如果系统较老，生成 4096 位 RSA 密钥
ssh-keygen -t rsa -b 4096 -C "[email protected]"

命令行会依次出现三个提示：

  1. Enter file in which to save the key (/home/user/.ssh/id_ed25519):
    • **直接按回车（Enter）**使用默认路径即可。
  2. Enter passphrase (empty for no passphrase):
    • 设置密钥密码（若个人电脑希望完全免密，直接按回车留空；若追求最高安全性可输入密码）。
  3. Enter same passphrase again:
    • 再次按回车确认。

3. 将 SSH 公钥添加到 GitHub

  1. 查看并复制公钥内容：

    # 查看 Ed25519 公钥内容
cat ~/.ssh/id_ed25519.pub

# 或者若为 RSA：
cat ~/.ssh/id_rsa.pub

    复制终端输出的整行字符串（以 ssh-ed25519 或 ssh-rsa 开头，以你的邮箱结尾）。

  2. 打开 GitHub 网站并登录：

    • 点击右上角个人头像 -> Settings（设置）。
    • 在左侧侧边栏中找到并点击 SSH and GPG keys。
    • 点击绿色的 New SSH key（添加新 SSH 密钥）。
    • Title：给这个密钥起一个有辨识度的名字（如 MacBook-Pro-Work、Home-Desktop）。
    • Key type：保持默认的 Authentication Key。
    • Key：将前面复制的完整公钥内容粘贴进去。
    • 点击 Add SSH key 保存。

4. 测试 SSH 连通性

在终端运行以下测试命令：

ssh -T [email protected]

首次连接时会提示服务器指纹信息：

The authenticity of host 'github.com (20.205.243.166)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuKeo9g...
Are you sure you want to continue connecting (yes/no/[fingerprint])?

输入 yes 并按回车。

若配置成功，将看到友好的欢迎信息：

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

这表明你的 SSH 密钥已成功与 GitHub 绑定！

二、Personal Access Token (PAT) 配置

如果你习惯使用 HTTPS 地址（如 https://github.com/username/repo.git），或者在不支持 SSH 的 CI/CD 容器中，需要使用 Personal Access Token (PAT) 代替传统密码。

1. 生成 Personal Access Token

GitHub 提供两种 Token：

  • Fine-grained personal access tokens（细粒度令牌，推荐）：支持按具体仓库和具体权限最小化授权。
  • Tokens (classic)（经典令牌）：全局范围授权，兼容性好。

以经典令牌为例：

  1. 访问 GitHub -> 右上角头像 -> Settings -> 页面最底部左侧 Developer Settings。
  2. 选择 Personal access tokens -> Tokens (classic)。
  3. 点击 Generate new token -> Generate new token (classic)。
  4. 填写配置项：
    • Note：令牌用途（例如 VSCode-Desktop、Ubuntu-Server）。
    • Expiration：有效期（建议选择 30/60/90 天或按需自定义）。
    • Select scopes：勾选权限。对于日常 Git 提交，必须勾选 repo（全部仓库访问权限）；若需要管理工作流可勾选 workflow。
  5. 点击底部绿色的 Generate token。
  6. 重要：生成后立即复制屏幕上的 Token（形如 ghp_xxxxxxxxxxxxxxxxxxxx）。离开该页面后将无法再次查看！

2. 在 Git 中使用 PAT 并配置凭据持久化

为了避免每次 git push 都需要手动复制粘贴长长的 Token，建议启用本地凭据管理器：

# Windows 系统（默认启用 Windows 凭据管理器）：
git config --global credential.helper manager

# macOS 系统（保存到系统钥匙串 Keychain）：
git config --global credential.helper osxkeychain

# Linux 系统（保存到本地加密或明文文件）：
git config --global credential.helper store

配置后，在下次执行 git push 时：

  • Username：输入你的 GitHub 用户名。
  • Password：输入你刚才生成的 Personal Access Token (ghp_...)。

凭据将被安全保存在本地，后续操作无需再次输入。

三、常见问题与报错排查（FAQ）

Q1: Permission denied (publickey). fatal: Could not read from remote repository.

原因分析：本地 SSH Agent 没有加载密钥，或者使用的公钥与 GitHub 上的不一致。
解决步骤：

  1. 确认密钥文件权限是否过宽（Linux/macOS 对权限要求严格）： 
    chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_ed25519
chmod 644 ~/.ssh/id_ed25519.pub
  2. 将私钥添加到系统的 ssh-agent 中： 
    eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

Q2: 电脑上有多个 GitHub 账号（如个人账号和公司账号），如何隔离？

在 ~/.ssh/ 目录下创建并编辑 config 文件：

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

# 公司/工作账号
Host github-work
    HostName github.com
    User git
    IdentityFile ~/.ssh/id_work

在克隆工作仓库时，只需将域名替换为配置的别名：

git clone git@github-work:company-org/project.git

Q3: 使用 HTTPS 方式克隆时网络太慢甚至连接超时怎么办？

若在拉取公共开源项目时遇到 HTTPS 网络超时，可以借助 GH-Proxy 加速下载：

# 原始命令
git clone https://github.com/torvalds/linux.git

# 结合 GH-Proxy 高速克隆
git clone https://gh-proxy.com/https://github.com/torvalds/linux.git

更多加速规则与全局重定向配置，可参考 Git 客户端全局配置。

💬 互动交流与反馈