DevOps知识中心
DevOps知识中心

使用 SSH 和令牌解决常见的 Git 身份验证错误

是否正在为 403 Forbidden 或重复的凭据提示等持续的 Git 身份验证错误而苦恼？本指南提供了从弃用的密码登录转向的专家级解决方案。了解 SSH 密钥的安全设置、如何为 HTTPS 生成和使用个人访问令牌 (PAT)，以及在 macOS、Windows 和 Linux 上配置操作系统原生凭据帮助程序的最佳实践。实施这些步骤以保护您的连接并永久解决身份验证问题。

43 浏览量

解决常见的 Git 认证错误：SSH 和令牌应用指南

认证错误是 Git 用户常遇到的痛点，尤其是在克隆（cloning）、拉取（pulling）或推送（pushing）代码时。持续的失败，通常表现为 fatal: Authentication failed 或 403 Forbidden 消息，表明 Git 无法与远程托管服务（如 GitHub、GitLab 或 Bitbucket）安全地验证您的身份。

这份详尽的指南将深入探讨这些故障背后的核心原因。我们将摒弃现在已基本弃用的简单用户名/密码提示，转而关注现代、安全的认证方法：SSH 密钥和个人访问令牌（PAT）。掌握这些技术对于可靠的开发工作流程至关重要，能确保您的凭据既安全又被 Git 提供商正确识别。

1. 诊断认证失败指示

在实施解决方案之前，了解 Git 失败的 原因 至关重要。认证错误通常源于两个主要原因：凭据过期或被撤销，或者为已存储的凭据使用了错误的协议（HTTPS vs. SSH）。

常见错误消息

  • 403 Forbidden: 这通常意味着您的连接尝试成功了，但提供的凭据（密码或令牌）没有完成操作所需的权限。
  • fatal: Authentication failed for 'https://...': 表明 Git 尝试使用已存储的凭据（通常通过凭据助手），但它们无效，或者未找到有效的凭据。
  • 密码提示循环： 如果您通过 HTTPS 被反复要求输入密码，这通常意味着您的托管提供商不再接受密码进行 Git 操作，而需要使用个人访问令牌。

识别您的连接类型

Git 根据远程 URL 方案以不同的方式进行认证。检查您的仓库的远程 URL：

git remote -v
URL 方案 所需认证方法
https://github.com/user/repo.git 通过 HTTPS 的个人访问令牌 (PAT)
[email protected]:user/repo.git SSH 密钥对

如果您打算使用 SSH 但远程 URL 是 HTTPS，反之亦然，您必须更改 URL 或切换认证方法。

从 HTTPS 切换到 SSH：

git remote set-url origin [email protected]:USERNAME/REPOSITORY.git

2. 解决方案 1：建立 SSH 密钥认证

SSH 密钥提供了与 Git 服务认证的最安全、最简化的方式，初次设置后无需后续密码提示。它们依赖于公钥/私钥对。

2.1 检查现有 SSH 密钥

验证您的机器上是否已生成 SSH 密钥对：

ls -al ~/.ssh

查找名为 id_rsa、id_ed25519 或类似的文件，以及对应的 .pub 文件（公钥）。

2.2 生成新的 SSH 密钥对

如果没有合适的密钥，请生成一个新的。Ed25519 是推荐的现代算法，尽管 RSA 4096 位也安全。

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

# 按照提示操作。强烈建议使用一个强密码短语。

2.3 在 Git 主机上注册公钥

公钥必须在您的 Git 主机（例如 GitHub 设置、GitLab 设置）上注册。

  1. 将公钥内容复制到剪贴板：
    bash cat ~/.ssh/id_ed25519.pub
  2. 导航到您的托管服务的设置，找到 SSH 密钥部分。
  3. 将公钥文件的全部内容粘贴到密钥注册字段中。

2.4 测试 SSH 连接

注册后，测试连接以确保主机识别您的密钥。使用以下命令，如有必要请替换 github.com：

ssh -T [email protected]

如果成功，您将收到一条欢迎消息，确认您的认证，例如：Hi USERNAME! You've successfully authenticated...

提示： 如果连接失败，请确保您的 SSH 代理正在运行并已加载您的密钥。使用 eval "$(ssh-agent -s)"，然后是 ssh-add ~/.ssh/id_ed25519（或您的密钥路径）。

3. 解决方案 2：为 HTTPS 使用个人访问令牌 (PAT)

如果您倾向于继续使用 HTTPS 远程 URL（或受限于无法使用 SSH），则必须使用个人访问令牌 (PAT) 而非您的账户密码。自 2021 年起，这是主要平台的一项关键要求。

3.1 生成个人访问令牌

PAT 直接在您的 Git 主机的安全设置中生成。

  1. 导航到设置： 前往您的个人资料设置，通常在“开发人员设置”或“访问令牌”下。
  2. 生成新令牌： 提供一个描述性名称并设置过期日期（最佳实践是设置过期日期，例如 90 天）。
  3. 定义范围： 至关重要的是，分配必要的权限（范围）。对于常规仓库访问，您通常需要 repo 范围。
  4. 保存令牌： 生成后，立即复制令牌。它不会再次显示。

警告： 请像对待密码一样对待您的 PAT。如果泄露，它将授予对您所分配范围的完全访问权限。

3.2 使用 PAT

当通过 HTTPS 执行 Git 操作时，系统会提示您输入用户名和密码。

提示 输入值
用户名： 您的实际 Git 用户名
密码： 完整的个人访问令牌 (PAT) 字符串

输入后，Git 通常会使用凭据助手（参见第 4 节）安全地存储此令牌。

4. 使用凭据助手管理凭据

重复输入冗长的 PAT 是不切实际的。Git 的凭据助手会安全地缓存或存储您的认证详细信息，因此您只需输入一次。

4.1 配置默认凭据助手

凭据助手管理 Git 如何保存您的认证信息。最安全的方法是利用原生操作系统安全存储。

对于 macOS： 使用钥匙串访问助手（通常默认启用）：

git config --global credential.helper osxkeychain

对于 Windows： 使用 Windows 凭据管理器：

git config --global credential.helper manager

对于 Linux： cache 助手可以临时存储凭据，但 store 助手会以未加密的方式存储它们（请谨慎使用）。

# 在内存中缓存凭据 1 小时（3600 秒）
git config --global credential.helper 'cache --timeout=3600'

4.2 重置已存储的凭据

如果您的认证错误持续存在，很可能是现有已存储（但无效）的凭据导致的。您必须清除已存储的凭据，以强制 Git 再次提示您输入 PAT。

如果使用 macOS 钥匙串：

  1. 打开“钥匙串访问”应用程序。
  2. 搜索 github.com 或您的 Git 主机。
  3. 删除相应的互联网密码条目。

如果使用 Windows 凭据管理器：

  1. 打开“控制面板”并导航到“凭据管理器”。
  2. 在“Windows 凭据”下，找到与 git:https://... 或您的主机域相关的通用凭据。
  3. 删除该条目。

清除旧凭据后，下一次 Git 操作（例如 git pull）将提示您输入用户名和新的 PAT，凭据助手随后会安全地存储它们。

总结与后续步骤

解决持续存在的 Git 认证错误，归结为确保您正在使用与您的远程 URL 协议（SSH 或 HTTPS）匹配的现代、受支持的凭据类型（SSH 密钥或 PAT）。

如果错误持续存在... 措施
403 Forbidden 验证 PAT 范围或检查主机上的 SSH 密钥权限。
重复提示（HTTPS） 生成个人访问令牌 (PAT)，并确保凭据助手正确存储它。
SSH 密钥失败 确认公钥已注册，并且 ssh-agent 正在运行并已加载私钥。

通过遵循这些步骤，您可以消除凭据错误，从而实现更顺畅、更安全的 Git 工作流程。