前两天有个同事跑过来跟我说git push 的时候明明输入的账号密码都是对的GitHub 却一直提示验证失败。我一看他还在用账号密码往 GitHub 推代码就知道问题出在哪了——这个坑几乎所有用过 GitHub 的人都会踩一遍而且踩完就忘过段时间换个电脑、换个环境又踩一次。其实 GitHub 早在 2021 年 8 月就正式停用了 HTTPS 的账号密码认证密码验证失败不是因为你记错了密码而是 GitHub 压根不想让你用这种方式认证了。这篇文章我就把 GitHub 账号密码验证失败的前因后果、标准解法、以及我实测过的几种替代方案完整写一遍给遇到同样报错的人一个可以直接照着操作的参考也帮已经用了 token 但时不时还会翻车的人排查一下问题到底出在哪个环节。1. 报错那一刻很多人第一反应是改密码其实是方向错了1.1 错误信息的几种常见长相先来对号入座看看你遇到的是不是下面这几类报错。因为是不同 Git 版本、不同操作系统、不同仓库地址报错的长相会有差异但底层逻辑是一样的。最常见的提示长这样remote: Support for password authentication was removed. Please use a personal access token instead. remote: Please see https://github.com/blog/... for more information. fatal: Authentication failed for https://github.com/xxx/yyy.git/还有一类是输入账号密码之后直接弹错误remote: Invalid username or password. fatal: Authentication failed for https://github.com/xxx/yyy.git/如果你用的是 macOS可能会看到fatal: The remote end hung up unexpectedly或者 Windows 环境下提示fatal: unable to access https://github.com/xxx/yyy.git/: The requested URL returned error: 403不管哪一种本质上都是 Git 在通过 HTTPS 协议访问 GitHub 远端仓库时提交的认证信息没有被接受。很多人看到Invalid username or password就跑去 GitHub 网页端改密码改完回来再试还是老样子然后陷入改密码-失败-再改密码的死循环。这就是没搞懂 GitHub 认证机制变化导致的。1.2 为什么还有人习惯用账号密码这套老流程2018 年之前GitHub 对 HTTPS 方式的 git push 是支持直接用账号密码认证的当时的教程满天飞基本都是git clone 下来push 的时候输入 GitHub 用户名和密码。很多人的肌肉记忆就是从那时候留下的以至于后来换了环境、换了电脑下意识还是用老一套。再加上 GitHub 的中文教程、培训机构课程更新速度参差不齐大量资料还在教输入账号密码完成 push。说实话我见过不少写了两年代码的同学直到某天 push 报错才知道 GitHub 已经改了认证规则。这不是个例几乎每个带新人的团队都会遇到同学问这个问题。1.3 改密码为什么没用要理解改密码为什么没用得先知道 GitHub 当时改了什么。2020 年 7 月 GitHub 官方就发布了公告计划逐步停止对密码认证的支持到了 2021 年 8 月 13 日所有依赖账号密码的 Git over HTTPS 操作正式失效。也就是说你账号本身的密码仍然可以用来登录网页版 GitHub、用来做账号安全设置但它已经不再被 Git 命令行的 HTTPS 通道接受。所以你在网页端把密码改得再复杂、再安全对 git push 这件事没有任何帮助。命令行这边要的不是账号 密码而是账号 个人访问令牌或者干脆走 SSH 密钥认证。想通这一点后面的操作就顺理成章了。2. 为什么 GitHub 在 2021 年之后就不认密码了2.1 密码天生不适合做 API 认证很多人不理解明明账号密码是人类最熟悉的认证方式为什么 GitHub 要顶着用户抱怨把它禁掉站在平台安全角度这个决策其实非常合理。密码是一种共享秘密只要你把密码输入到某个地方那个地方理论上就有能力和权限读取并保管你的密码。Git 命令行每次 push 都要输入密码这意味着用户的密码会频繁出现在终端历史、脚本、自动化任务、第三方工具里泄露面被无限放大。一旦某个环节没有做好防护比如本地的 shell history 记录了包含密码的命令、某个 GUI 工具把密码明文存在配置文件里攻击者拿到密码就等于拿到了你整个 GitHub 账号的控制权包括所有仓库、所有代码、所有私密项目。而 Token 可以看成是一把带权限的钥匙。你可以只给它读取公开仓库的权限也可以只给它推送到某个仓库的权限甚至可以设置它 30 天后自动过期。即使某把钥匙泄露了你单独吊销它就可以了不需要改密码也不影响其他场景的登录。SSH 密钥也是类似的逻辑它是非对称加密私钥留在本地公钥交给 GitHub泄露和吊销的处置都更灵活。2.2 GitHub 官方的切换时间线给一个清晰的时间线方便你理解这件事不是临时出 bug而是确定性的规则变更2020 年 7 月GitHub 宣布将从 2021 年开始移除密码认证要求开发者改用 Token 或 SSH。2020 年 11 月前后GitHub 开始对部分用户进行灰度验证强制要求使用 Token。2021 年 8 月 13 日完全移除密码认证HTTPS 方式只接受账号 Personal Access Token。这个时间线也解释了为什么网上能找到各种说法。如果你查的资料是 2021 年 8 月之前发布的那它教你的输入密码就能 push在当年确实是可行的只是放到现在就失效了。大家在搜索引擎里看到的答案混杂了不同时间段的经验所以很多人会来回试。2.3 账号密码验证失败背后发生了什么从通信层面看Git 通过 HTTPS 访问 GitHub 时使用的是 HTTP Basic Authentication。默认情况下当 git push 到一个需要认证的仓库时Git 会提示你输入用户名和密码然后把这些信息拼到 HTTP 请求的 Authorization 头里发给 GitHub。GitHub 收到请求后会检查这个用户名和密码是否匹配如果不匹配就返回 401 或 403Git 再把错误展示成Authentication failed。GitHub 禁用了密码认证之后后端干脆不再接受密码这种凭据类型。你输入的密码无论是否正确都会被视为无效凭据返回的提示也变成了那句著名的 Support for password authentication was removed。所以你会看到密码明明没记错却始终失败因为 GitHub 服务器在逻辑上已经把你的密码当作不存在的认证方式来处理了。3. 最直接的办法用 Personal Access Token 完成认证3.1 创建 Token 的完整步骤既然账号密码不行第一步就是去生成一个 Personal Access Token。它本质上是 GitHub 发给你的一串随机字符用在 git push 时替代密码。操作路径是登录 GitHub 网页端 → 右上角头像 → Settings → 左侧最底部 Developer settings → Personal access tokens → Tokens (classic)。如果你的 GitHub 账号比较新界面里还会看到一个 Fine-grained tokens 的选项它权限更细但配置也相对复杂新手先从 Tokens (classic) 开始就行。点击 Generate new token (classic)会要求你填写 Note备注比如 my-home-pc和 Expiration过期时间。过期时间我建议选短不选长最长也不要超过 90 天因为 Token 的过期机制本身就是一种安全保险你完全可以在它过期后重新生成一个。Select scopes 这里最核心的是勾选 repo 这一项它代表对仓库的读写权限日常推送代码够用了。如果你需要同时操作 GitHub Actions 工作流文件.github/workflows 目录还需要勾选 workflow 权限。选完后点击 Generate token页面会显示一串以 ghp_ 开头的字符这个只会完整显示一次一定要立刻复制保存到你自己的密码管理器里。3.2 在 HTTPS push 时用 Token 替换密码拿到 Token 后回到命令行再执行 git push当 Git 提示输入 Username 时输入你的 GitHub 用户名不是邮箱提示输入 Password 时把刚才复制的那一串 Token 粘贴进去按回车。注意这里粘贴 Token 时终端不会显示任何字符看起来像是没输入其实是正常的粘贴完直接回车就行。git push origin main Username for https://github.com: yourname Password for https://yournamegithub.com: 粘贴你的Token只要 Token 权限和过期时间没问题push 就能成功。如果你嫌每次都要输入太麻烦可以跳过手动输入直接把远程地址改成带 Token 的格式。不过我个人不建议把 Token 拼进远程 URL 里因为那样你的 Token 会出现在 .git/config 文件里万一这个目录被上传或者被别人看到Token 就泄露了。正确做法是让 Git 的凭据管理器帮你记住 Token。3.3 让 Git 记住 Token避免每次手输Git 自带凭据存储机制你可以通过配置来选择存凭据的方式。git config --global credential.helper store这个命令会把凭据明文保存在 ~/.git-credentials 文件里。优点是很简单缺点是明文存储不适合对安全要求高的环境。还有一个相对稳妥的选择是用 Git 默认的 credential managerWindows 上通常自带 Git Credential ManagermacOS 上会使用钥匙串Keychain配置方式基本不需要额外操作。git config --global credential.helper manager-core或者直接不设置Git 在第一次 push 失败后通常会弹出系统凭据管理器窗口你按提示填入用户名和 Token它就会保存下来之后 push 不再提示。这里有个容易踩的坑如果你之前已经用旧密码保存过一次凭据那么凭据管理器里存的还是旧密码即使你后来生成了新 Token它也一直用旧密码去认证结果还是 Authentication failed。这种情况需要你把已保存的凭据删掉再重新输入一次具体操作我在第 5 节详细说。3.4 Token 过期和权限不够的坑Token 最大的坑就是过期。GitHub 默认生成的 Token 是有有效期的短则 30 天长则一年或自定义。Token 过期后的报错通常不是 password authentication was removed而是remote: Invalid username or password. fatal: Authentication failed for https://github.com/xxx/yyy.git/我见过不少同学看到这个报错以为又是密码问题去改密码折腾半天才发现是 Token 过期了。所以遇到 Authentication failed第一件事先检查 Token 是否过期第二件事检查权限范围是否覆盖了你操作的内容。尤其是 Fine-grained token如果你只给它配置了某个仓库的读取权限却想往另一个组织仓库推代码GitHub 会直接拒绝报错信息还不会写得很明白。4. 我更推荐的长久之计切到 SSH 密钥认证4.1 为什么 SSH 认证更适合日常推送Token 方案虽然能解决问题但它有个绕不开的缺点你要管理 Token 的生成、保存、过期、续期多台电脑就要管理多个 Token团队协作时还要注意不要把自己的 Token 泄露到公共环境。相比之下SSH 密钥认证一旦配置好几乎是一劳永逸的。SSH 的原理是你本地生成一对密钥私钥 公钥把公钥上传到 GitHub私钥留在本地。push 的时候GitHub 用公钥验证你的身份而私钥从头到尾不会离开你的电脑不需要像 HTTPS 那样每次输入账号密码。日常使用中只要你本地 SSH agent 正常启动了git push 全程无感丝滑得多。4.2 生成并配置 SSH 密钥的完整过程第一步检查一下本地是否已经有 SSH 密钥。一般看 ~/.ssh 目录下有没有 id_ed25519 或 id_rsa 这类文件。ls -al ~/.ssh如果没有用下面的命令生成一份新密钥。GitHub 官方现在推荐使用 ed25519 算法安全性高、生成速度快兼容性也好。ssh-keygen -t ed25519 -C your_emailexample.com执行后会要你选择保存路径和设置 passphrase。保存路径直接回车用默认的就行passphrase 建议设一个简单的短语相当于私钥的二次密码防止电脑被别人拿到后直接滥用私钥。当然你也可以不设代价是私钥文件被别人拷走就能用。生成完成后把公钥内容复制出来。macOS 和 Linux 直接输出到屏幕再复制cat ~/.ssh/id_ed25519.pubWindows 用 type 命令或者用记事本打开对应文件。复制一整行ssh-ed25519 AAAA...开头的字符然后打开 GitHub 网页端Settings → SSH and GPG keys → New SSH key把公钥粘贴进去Title 随便填一个能让你分辨是哪台电脑的名字即可。接下来把本地仓库的远程地址从 HTTPS 切换成 SSH 格式。这个是对你踩坑最关键的步骤之一很多人以为生成完公钥就完事了结果 remote URL 还是 https 开头SSH 密钥压根没参与认证。git remote set-url origin gitgithub.com:你的用户名/你的仓库名.git然后验证连接是否正常ssh -T gitgithub.com第一次连接会提示你是否信任 GitHub 的主机指纹输入 yes 后返回Hi xxx! Youve successfully authenticated, but GitHub does not provide shell access.就说明 SSH 通了。再执行 git push你会发现完全不需要输入任何账号密码。4.3 多账号和端口 443 的 SSH 配置技巧一个容易被忽视的场景如果你有多个 GitHub 账号或者同时使用 GitHub 和 GitLab就需要在 ~/.ssh/config 文件里做区分。假设你有个账号 A 用于个人项目账号 B 用于公司项目可以这样配置Host github-work HostName github.com User git IdentityFile ~/.ssh/id_ed25519_work Host github-personal HostName github.com User git IdentityFile ~/.ssh/id_ed25519_personal然后把对应仓库的 remote URL 里的 gitgithub.com 换成 gitgithub-work 或 gitgithub-personal比如git remote set-url origin gitgithub-work:你的公司用户名/仓库名.git另一个实用技巧是 SSH over 443。有些网络环境会屏蔽 22 端口导致ssh -T gitgithub.com超时或者连接被拒但 443 端口通常是放开的。GitHub 官方支持通过 ssh.github.com:443 连接你只需要在 ~/.ssh/config 里加上Host github.com HostName ssh.github.com Port 443 User git改完后再试ssh -T gitgithub.com一样能通。这属于 GitHub 官方提供的常规连接方式并不是什么旁门左道。4.4 SSH 方式的典型报错及处理SSH 认证的报错比较固定最常见的两个Permission denied (publickey)说明 GitHub 没有识别到你的公钥或者私钥没被加载。先确认公钥确实添加到了 GitHub 账号里再确认本地 SSH agent 加载了私钥。可以用ssh-add -l查看当前加载的密钥列表。Host key verification failed多半是你重装系统、换过密钥后本机的 known_hosts 里还残留旧指纹。删除 known_hosts 里对应条目重新连接即可。还有一个容易被忽略的点如果你在同一台机器上配置了多个私钥SSH 会默认按顺序尝试。如果没有在 config 文件里指定 IdentityFile可能会用错私钥导致 GitHub 一直告诉你 Permission denied。这时候把 IdentityFile 指定清楚问题立刻解决。5. 排查改了 token 还是不行的几类真实场景5.1 场景一用户名写错或大小写不对有些人在 Git 提示 Username 时习惯性填了邮箱或者填了不带前缀的仓库名这些都是不对的。HTTPS 认证时 Username 必须是你的 GitHub 登录用户名邮箱不行。虽然 GitHub 对用户名大小写不敏感但建议直接按你账号主页里显示的名字填避免肌肉记忆出错。5.2 场景二系统凭据管理器里存着旧密码这是最隐蔽也是最高频的坑。Windows 上 Git 第一次提示输入密码时如果你用的是 Git Credential Manager它会把凭据存进 Windows 凭据管理器。之后就算你生成了新 Token它依然会用旧凭据去认证。处理方法Windows控制面板 → 用户账户 → 凭据管理器 → Windows 凭据找到 github.com 开头的条目删除。macOS打开钥匙串访问搜索 github删除对应条目。Linux看你配置了哪种 credential.helperstore 类型直接删除 ~/.git-credentials 里的相关内容。删除之后重新 pushGit 会再次提示输入用户名和 Token这次输入的会被保存下来。5.3 场景三仓库 URL 还带着旧的令牌参数如果之前有人用https://你的用户名:ghp_xxxgithub.com/xxx/yyy.git这类格式配置过远程地址即使你现在换了新 Token远程地址里写死的旧 Token 也会一直在。检查方式git remote -v如果发现 remote URL 里带着一串 前面有 token 的情况用git remote set-url把它改成干净的 HTTPS 地址或 SSH 地址。5.4 场景四多个 SSH 密钥用错了前面提到过多账号场景下如果没有在 ~/.ssh/config 里明确指定密钥SSH 可能会用一个 GitHub 上不存在的公钥去尝试认证报错看起来像是密钥的问题实际是选择错了私钥。给每个账号单独建一个 Host 别名并加验证ssh -T git别名逐个确认能对上号。5.5 场景五Token 权限没勾全push workflow 文件被拒很多人勾选了 repo 后发现普通代码能 push但一碰 .github/workflows 目录就报错提示refusing to allow a Personal Access Token to create or update workflow event。这是因为你生成 Token 的时候没勾选 workflow 权限。GitHub 对 workflow 文件的操作有单独的权限管控需要专门在 Scopes 里勾上workflow再生成新 Token 才能解决。为了方便你快速定位我把常见的报错、原因和解决办法整理成一张表报错表现大概率原因解决办法Support for password authentication was removed还在用账号密码做 HTTPS 认证改用 Personal Access Token 或 SSHInvalid username or passwordToken 过期 / Token 权限不足 / 用户名填错重新生成 Token确认用户名和权限范围403远程 URL 里的旧 Token 失效重新设置 remote URL清空旧凭据Permission denied (publickey)公钥未添加 / 私钥未加载检查 GitHub 公钥配置和本地 ssh-agentrefusing to allow a PAT ... workflowToken 缺少 workflow 权限生成 Token 时勾选 workflow scope5.6 排查顺序建议当你再次遇到 push 认证失败我建议按这个顺序快速过一遍先git remote -v看远程地址类型是 HTTPS 还是 SSH再git config --list看全局和本仓库的配置有没有异常的 credential helper然后去凭据管理器里清掉旧凭据最后检查 Token 的有效期和权限。大多数问题都集中在这四步里。试完还不行就去 GitHub 官网登录网页端看账号有没有异常比如组织是否有二次验证要求。6. 一些关于凭据管理和团队协作的额外提醒6.1 密码不会消失但它不再是命令行认证的入口很多人在处理完这次报错之后会下意识觉得那我的 GitHub 密码是不是没用了。并不是。网页登录、账号安全设置、两步验证这些场景仍然需要密码。只是命令行、API、第三方工具的认证入口从账号 密码变成了账号 Token或SSH 密钥。把这两套体系分开理解以后就不会再搞混了。6.2 团队协作时别把 Token 提交进仓库我看过最吓人的操作是有人为了省事把 Token 直接写进 .git/config然后整个目录被打包发到群里共享。Token 一旦进了别人的手里对方可以用你的身份对仓库做任何你想不到的操作。团队协作时正确的做法是每个人都有自己独立的 GitHub 账号每个人用自己的 Token 或 SSH 密钥认证权限按需分配。另外如果你的仓库里存在任何形式的.env、配置文件、脚本里面写有 ghp_ 开头的字符串建议立即去 GitHub 的 Settings → Security log 里检查有没有异常访问同时吊销那个 Token 并重新生成。6.3 一个实用的小习惯把认证方式写进项目 README我自己的习惯是在每个项目的 README 开头加一小段开发环境指南里面明确写一句推代码请使用自己的 GitHub 账号完成认证不要共享账号也不要复制别人的 Token。这对新成员尤其有用能在第一天上手时就避开这个认证坑省得每次都要被同一个问题卡住再花半小时排查。最后再分享一个我自己的经验遇到这类认证问题最忌讳的是试一个方法不行马上换另一个。先把报错原封不动读完再把 remote 地址、凭据管理器、Token 有效期这三个最基础的环节检查完再考虑去查别的资料。我这些年帮别人处理过至少二三十次类似的问题绝大多数都逃不出这几个范围。希望这篇内容能让你少走几趟弯路。
