最近有个朋友半夜发消息说 CI 挂了。日志里反复出现“sign-in could not be completed token exchange failed: error sending request”他以为 token 又过期了重新生成三次还是不行。我远程看了一圈才发现报错文案一样但根因根本不是 token 本身而是权限配置和本地凭证缓存叠在一起的“综合症”。GitHub Token 权限错误就是这么折磨人——它常常顶着同一个报错背后却是完全不同的原因。这篇文章我想把这类问题完整拆一遍Token 权限错误到底有哪些常见形态、为什么明明填了 Token 还是 403、从命令行到网页端该怎么一步步定位根因还有我踩过几次之后总结的预防手段。不管你是刚接触 Git 的新手还是被 CI/CD 折腾了很久的开发者只要和 GitHub 的 token 打过架这篇应该对你有用。先说好这里的 token 是 GitHub 的访问凭证不是大模型那边按 token 数计费的那种虽然名字一样逻辑完全不同。1. 先复盘一次真实的 Token 权限翻车现场1.1 那个让人摸不着头脑的报错文案有一次我用 GitHub CLI 重新登录输入用户名后弹出完整的一段错误sign-in failed: login server error: token exchange failed: token endpoint returned status 403 forbidden: country当时我第一反应是 token 的权限不够于是跑到 Settings - Developer settings 里重新生成一个带着全部 repo scope 的 token结果再次登录还是同样的错误。后来我把 GIT_TRACE 打开才发现本地 Git 还在使用 Windows 凭据管理器里的旧 token新 token 根本没机会出场。这类错误最迷惑的地方在于提示信息里写的是“token exchange failed”可能的原因却横跨网络、时间、权限、缓存。很多时候我们去网上搜索看到的答案五花八门让人越试越乱。所以不要一上来就重新生成 token而是先看完整日志。要养成一个习惯报错出来先截图留证至少记下完整的错误文案和当时的操作命令。很多“权限错误”其实根本不是权限而是前面的步骤出了问题错误信息只是一层壳。1.2 我把 GitHub Token 错误分成了四类经过很多次排查我会把遇到的 GitHub Token 权限错误先分类再对症下药。分类能大幅缩小排查范围避免在错误的方向上反复折腾。第一类认证失败类。典型文案有 “Authentication failed”、“Bad credentials”、“sign-in could not be completed token exchange failed”。这类通常指向 token 本身无效、格式错误或者根本没有 token。第二类授权不足类。典型文案是 403 “Permission denied”、“must have push accesses”、workflow 权限不足。这类说明 token 是有效的但 scope 或者仓库权限没给到操作所需的最低要求。第三类令牌失效类。包括 “Token has expired”、“Your access token could not be refreshed”、还有常见的 “invalid refresh_token: empty string”。这类跟 token 的生命周期管理有关尤其是过期时间、刷新令牌以及本地存储的凭证残留。第四类环境干扰类。表现是 “error sending request”、连接超时、TLS 握手失败、SSL certificate problem。这类和 token 内容无关但在 log 里依然会跟 token 错误混在一起。我用一张表来整理常见的报错文案和优先排查方向方便你排查时对照报错文案常见变体错误类别优先排查方向Bad credentials / Authentication failed认证失败token 是否正确、是否过期、有没有复制完整sign-in could not be completed token exchange failed认证失败环境干扰网络连通性、本地凭证缓存、时间同步403 Permission denied授权不足scope 是否覆盖操作、组织 SSO 是否已授权Your access token could not be refreshed令牌失效刷新令牌机制、是否重新登录invalid refresh_token: empty string令牌失效代码中刷新令牌的读取与存储error sending request / SSL certificate problem环境干扰网络可达性、系统时间、安全软件拦截表格整理好之后接下来做初步自检。这一步的目标是把“环境干扰”和“权限本身”分开不让网络问题伪装成权限问题。1.3 排查前必须确认的三件事第一件事确认当前 token 是否真的有效。打开终端执行下面的命令看当前登录状态gh auth status --show-token如果gh没有安装可以直接看本地 Git 配置git config --list --show-origin | grep -i remote第二件事确认 Git 正在使用的凭证来源。Git 默认的凭证助手可能是 cache、store也可能是 manager-core。先看配置git config --global credential.helper如果输出是manager或manager-core说明走的是系统凭据管理器。这时哪怕你生成一个新 token 放在环境变量里Git 可能依然优先用凭据管理器里的旧 token。很多“我明明改了 token 却没用”的情况都是这个原因。第三件事确认 API 端点通不通。用下面的命令请求一下 GitHub API不看业务数据只看 HTTP 状态码curl -i -s -o /dev/null -w %{http_code} https://api.github.com正常会返回 200 或 301。如果是 403 但 body 里有 rate limit 提示那又是一种情况。如果直接连接失败或者返回一个奇怪的 HTML 错误页那就要先解决连通性再回来谈 token。这三件事做完基本能把“网络问题”和“权限问题”分开。接下来就是深入理解权限规则的时候。2. 读懂 Token 的权限规则才能知道 403 到底在拦谁2.1 经典 PAT 和细粒度 PAT区别不止是名字GitHub 现在提供两种 token经典 Personal Access Tokenclassic PAT和细粒度 Personal Access Tokenfine-grained PAT。很多人只知道去 Settings 里 Generate new token却不知道这两者的权限模型完全不同。经典 PAT 的权限靠 scope 控制比如repo是一整组仓库读写权限workflow可以更新 GitHub Actions 工作流文件。它生成之后通常不会立刻过期除非你手动 revoke。但正因为权限粒度粗很多人图省事直接勾选所有 scope反而埋下安全风险也容易在组织仓库里遇到额外的 SSO 拦截。细粒度 PAT 可以限制到指定仓库、指定权限类别和有效期甚至可以把 token 的失效时间设置得很短。它的权限不再是repo这种大而全的 scope而是拆成比如Contents: Read and write、Pull requests: Read and write这种具体权限。用细粒度 PAT 的时候最容易犯的错是只给了Metadata: Read然后想 push 代码Git 就报 403 Permission denied。所以在生成 token 之前先想清楚你的操作需要哪些权限。如果是个人开发机经典 PAT 图省事如果是 CI/CD 或自动化脚本强烈建议用细粒度 PAT并把仓库和权限收敛到最小范围。最小权限原则在这里不是一句空话它能让你定位错误时更快。2.2 Scope 和仓库权限的匹配规则GitHub 的权限检查并不是“你有 token 就能干活”而是先认证你是谁再检查这个 token 对你操作的目标仓库有没有对应的权限。举个例子你想往仓库推送代码Token 必须包含对目标仓库Contents的写入权限。用经典 PAT 就是勾选repo覆盖所有仓库的读写用细粒度 PAT 就是在对应仓库上把Contents设置为Read and write。两者缺一不可。还有一类很隐蔽的问题workflow权限。如果你尝试通过 API 或者 git push 修改.github/workflows/目录下的文件token 需要额外拥有workflowscope。经典 PAT 要单独勾选细粒度 PAT 要在仓库权限里把Workflows打开。很多 CI 失败就卡在这一步报错往往是很模糊的 “Resource not accessible by integration” 或者 403。另外要区分 401 和 403。401 表示“你是谁没有被证明”通常是因为 token 错误、过期或根本没传403 表示“你已经过了认证但没权限做这个动作”。如果看到 403优先检查权限范围、SSO 授权而不是疯狂重新生成 token。权限匹配的逻辑其实很像门禁卡卡本身有效只是第一步你要进的房间属于哪一级权限还得单独看你的门禁等级。2.3 组织 SSO 的隐藏门槛如果你访问的是组织organization下的私有仓库而该组织启用了 SAML SSO事情会多一道手续即使 token 里的 scope 完全够GitHub 仍然会在第一次使用这个 token 访问组织资源时要求你做 SSO 授权。症状非常典型token 在个人仓库上一切正常一碰组织仓库就 403。很多人这时候去怀疑 token 的 scope 不够其实真正的解决方式只有一步——回到 GitHub 网页端打开 token 编辑页面找到该组织所在的条目点击 “Configure SSO”然后按提示完成一次组织层面的授权。授权完成之后这个 token 才能访问该组织的仓库。如果你刚加入一个公司组织用了旧个人 tokenGitHub 会明确要求重新授权甚至在刷新 token 时会报 “token exchange failed” 类似的东西。这类容易被忽略但排查链路很短先确认目标仓库是不是组织仓库再确认组织是否启用了 SSO最后检查 token 页面里的 Authorized organizations 列表。2.4 过期策略和 refresh_token 是另一层逻辑除了 PAT还有一类在 OAuth App / GitHub App 场景下流行的 token 机制access_token 过期之后用 refresh_token 换取新的 access_token。很多项目把这种机制做成了“让用户免重新登录”的长期凭证但处理不好会留下非常隐蔽的坑。最常见的报错是下面这种failed to refresh token: 400 bad request: invalid refresh_token: empty string. expected a string with minimum length 1, but got an empty string instead.看到这个报错第一反应不该是去找 GitHub 配置而是去查代码。refresh_token 是空字符串通常意味着你在存储或读取时把字段弄丢了。常见原因有三个一是从授权回调里取 token 时把 JSON 里的字段名写错成access_token而忽略了refresh_token二是把 refresh_token 存在 localStorage结果序列化时它被自动转成了字符串取回来后类型不对三是使用 OAuth 库时没有正确配置离线访问权限服务端根本没返回 refresh_token。如果你用的是 GitHub App 的 OAuth 流程确认回调地址是否和 GitHub App 配置的 Redirect URI 完全一致否则拿不到完整的 token 响应。遇到这种问题最快的验证方式是把授权接口返回的完整 JSON 打印出来看 refresh_token 到底有没有。如果响应里根本没有那是授权参数的问题如果响应里有但代码存下来后变成了空串那是存储层的问题。3. 一次完整的排查链路从 CLI 报错到根因落地的六个步骤3.1 第一步让错误信息“留证”别只盯着最后一行当你遇到 token 相关报错第一件事不要急着重试先开详细日志。Git 支持环境变量级别的调试信息可以让你看到 HTTP 请求的具体流程GIT_CURL_VERBOSE1 GIT_TRACE1 git push origin main运行之后你会看到 Git 和 GitHub 服务器之间的完整交互包括请求头、响应状态。重点看两个位置认证请求的 URL 是什么、响应里的 HTTP 状态码是多少。比如 token exchange failed 的时候日志里往往能看到 OAuth 端点返回了 400 或 403。记下这个 URL 和状态码后面排查就有的放矢。如果日志太长把输出重定向到文件GIT_CURL_VERBOSE1 GIT_TRACE1 git push origin main 2 git-debug.log然后查文件里的Authorization头和最后的 HTTP 状态。有一点必须注意debug 日志里可能包含 token 明文看完立刻删除日志文件不要随手发到聊天工具里。这个习惯我在很多项目里反复强调因为 token 泄漏的后果比权限错误麻烦得多。3.2 第二步用 gh CLI 自检认证状态GitHub 官方 CLI 是排查 token 问题最好用的工具。先运行gh auth status它会明确告诉你当前以哪个用户身份登录token 是否有效以及这个 token 访问哪些 host。想看看 token 本身有没有过期可以加参数gh auth status --show-token这个命令会明文显示 token所以看完后要留意终端历史记录不要在共享屏幕上运行。如果你发现 gh 显示未登录或者显示的用户不是预期的人直接用gh auth login重新走一遍交互流程。在 HTTPS 模式下gh auth login会自动把凭证写入 Git 的凭据管理器比你手动改 remote URL 更不容易出错。gh CLI 还有一个隐藏优势它可以帮你测试 token 和组织 SSO 的匹配状态。运行gh api user如果返回当前用户信息说明 token 基础认证有效再运行gh api repos/{org}/{repo}测试组织仓库访问如果这里 403那基本锁定到 SSO 授权或 scope 问题。3.3 第三步清理本地凭证缓存这是全流程里最容易翻车也最容易解决的一步。很多“重新生成 token 后仍然 403”的案例根因都在于本地 Git 凭据管理器还在用旧 token。在 Windows 上如果你之前用过 GitHub Desktop 或 Visual StudioGit 默认配置的 credential helper 常常是manager-core它会从 Windows 凭据管理器读取旧凭证。在 macOS 上它可能读取钥匙串。你需要在对应的凭据管理界面里找到git:https://github.com这一项删掉它。如果不确定在哪可以直接重置 Git 的 credential helper让 Git 下次重新向你索要凭证git credential-manager github login这条命令会弹出授权窗口重新登录后会自动覆盖旧凭证。更粗暴但有效的做法是先在系统设置里删除所有与 GitHub 相关的旧凭据然后再执行一次git push让 Git 询问新 token。这一步做完往往能解决一大批“我改了什么都没用”的诡异问题。记住一个原则你脑海里认为 Git 在用的 token和它真正从凭据管理器里拿出来的 token可能不是同一个。先清缓存再谈其他。3.4 第四步用 API 验证权限边界在修改任何配置之前先借助 API 验证当前 token 到底有哪些能力。用三个请求可以快速画出一个权限地图。第一验证用户身份curl -i -H Authorization: token $GITHUB_TOKEN https://api.github.com/user第二验证目标仓库的读取和写入权限。读取权限可以直接请求仓库信息curl -i -H Authorization: token $GITHUB_TOKEN https://api.github.com/repos/{owner}/{repo}写入权限的验证稍微复杂你可以尝试用这个 token 往一个测试分支推送空提交。为了避免污染主分支先建一个新分支git clone https://github.com/{owner}/{repo}.git cd repo git checkout -b test-token-check git commit --allow-empty -m token check git push origin test-token-check如果这个 push 成功说明 push 权限是够的如果 403说明 scope 或仓库权限不足。第三如果涉及 workflow 文件去更新一个.github/workflows/下的文件试试或者调用 API 查一下 actions 权限curl -i -H Authorization: token $GITHUB_TOKEN https://api.github.com/repos/{owner}/{repo}/actions/permissions这一套跑完你就能明确知道当前 token 卡在哪一层是身份认证没过去、仓库权限没给够、还是 SSO 没授权。后面修改配置就有方向了。3.5 第五步检查系统时间与网络出口说句实话很多 token exchange failed 的报错最后查出来是本地系统时间不对。GitHub 的 OAuth 服务在签发和验证 token 时依赖时间戳如果本地时间偏差太大TLS 证书验证或者 token 签名验证都会失败。Windows 和 macOS 一般会自动同步时间但如果设备休眠很久时间漂移是真实存在的。可以先手动同步一次时间sudo ntpdate -u pool.ntp.org或者用系统自带的自动时间同步。同步完再做一次 GitHub API 请求如果原来报 token exchange failed很多时候会突然恢复正常。另一个要查的是网络出口。如果你的网络环境存在防火墙或安全软件Git 发往https://api.github.com的请求可能被拦截表现为error sending request。这时候不要先怀疑 token先确认curl -I https://api.github.com如果返回的头里有X-GitHub-Request-ID说明网络链路基本通畅如果连不上、超时或者返回奇怪的内容问题在本地网络环境不是在 token 上。这种时候需要找你的网络管理员确认出口策略而不是反复修改 token。需要特别提醒我这里说的网络出口是正常的网络运维范畴。如果你正在使用任何非正规的网络接入工具请立刻停下那些工具既不稳定也容易让账号触发风控官方从来不会认可这种使用方式。正规的解决路径是让请求走你单位或自己可控的合规网络。3.6 第六步重新生成并授权 token前面五步走完问题基本定位到 token 权限本身。这时再去网页端生成新 token登录 GitHub进入 Settings - Developer settings - Personal access tokens。如果只是想快速解决个人仓库问题选 Tokens (classic)然后按需勾选 scope。如果是给 CI/CD 用选 Fine-grained tokens把权限精确到仓库级别。生成之后如果目标仓库属于组织且开启了 SSO回到同一个页面找到你的 token点 “Configure SSO” 完成组织授权。这一步很多人会漏掉。我以前就遇到过团队里同事新生成一个 tokenscope 看起来全选了但组织仓库依旧 403最后发现是 SSO 那一步没有点。新 token 生成后先不要直接替换到 CI 配置文件里先放到本地环境变量做一个最小化测试。测试通过再把它填到 CI 的 secret 或 Actions secrets 里。整个过程多花五分钟却可以避免新 token 再次踩同样的坑。4. 那些差点让我放弃排查的“烟幕弹”4.1 403 forbidden: country 到底在提示什么这个报错最近问的人很多很多人看到 country 就觉得是地区被限制了于是想到各种非常规手段。但真相没那么简单。GitHub 的 OAuth 端点和 API 端点会有自己的风控逻辑遇到异常请求模式时会返回 403错误描述里的 country 指的是服务端根据出口 IP 判断的地理区域风险状态。如果你的出口 IP 落在高风险区域服务端确实会直接拒绝这个 token exchange 请求。此时最理性的做法是确认当前网络出口是不是你平时正常的网络环境。如果你在公司或学校网络里找网管确认出口 IP 的归属如果在自己可控的网络环境先看看是不是某种全局网络软件改了你的出口 IP。任何通过伪装来源 IP 的方式绕开风控都是在跟平台安全策略对着干账号被限制只是时间问题。合规的解决思路很朴素确保请求从正常、可信、可追溯的网络环境发出必要时联系 GitHub 支持团队说明你的使用场景。4.2 refresh_token 为空字符串代码吞了还是平台变了这类报错常见于自建 OAuth 流程或第三方登录集成。我见过最气人的一个案例是后端接收 GitHub OAuth 回调后把整个响应对象存进了数据库然后某个函数读取时直接用resp[refresh_token]取字段结果这个字段在响应里根本没有——因为那一次授权流程没有请求离线访问权限。看着像 token 权限问题其实是授权参数配置问题。给一段伪代码示意错误的读取方式data response.json() refresh_token data[refresh_token] # 如果平台没返回这里直接抛异常正确的做法是先判断字段是否存在并且确保发起授权时配置好刷新令牌的参数data response.json() refresh_token data.get(refresh_token, ) if not refresh_token: # 回到登录流程重新发起带离线/刷新权限的授权 raise AuthenticationError(no refresh_token found, check OAuth params)关键在于遇到 refresh_token 相关错误不要在 GitHub 设置里反复折腾而是先打印出 GitHub 返回的完整响应体看看有没有这个字段。同时检查你用来存储 token 的数据库或缓存看是不是有序列化问题把它清空了。这类问题通常代码修一行就能解决但排查方向错了能折腾一整天。4.3 本地旧凭证永远比你的新 Token 优先前面提到过清理凭据管理器这里再说一个容易踩到的细节即使你更新了远程仓库的 remote URL例如把 token 直接拼到 URL 里当你 push 时 Git 依然会先用旧凭证去尝试。很多 CI 脚本在本地调试时都有这个现象。举个例子你在仓库里执行了git remote set-url origin https://x-access-token:ghp_xxxgithub.com/owner/repo.git理论上这个 URL 里带了新 tokenGit 应该直接用。但如果系统凭据管理器里已经有一份旧的git:https://github.com凭证Git 有时还是会先取旧凭证。解决办法有两个一是按 3.3 的步骤清掉旧凭证二是用GIT_ASKPASStrue强制 Git 使用 URL 中的用户名密码不过这招在不同版本里行为有差异不如清缓存稳定。说到这我多提醒一句把 token 直接拼在 remote URL 里这种方式只适合一次性测试千万别写进公开脚本或仓库配置。它很容易被git remote -v看到也会出现在日志里。测试完记得马上把 remote URL 改回不带 token 的形式。4.4 “network service 用户组”和“完全控制权限”是另一个故事热搜里经常混在 GitHub token 问题里的还有一类 Windows 上的服务权限错误。比如事件查看器里出现“方法失败、意外”或者 docker 启动时报“权限错误”解决方法是“添加 network service 用户组同时放开完全控制权限”。这个跟 GitHub Token 权限错误完全不是一个领域但搜索时很容易被并到一起。看到这类关键词要警惕先看报错来自哪个程序。如果是 Docker Desktop 或 Windows 服务报错那是系统账户对某个目录或注册表项的访问权限问题应该去检查服务账户和文件 ACL而不是去 GitHub 后台折腾。同样的道理如果你在某个问题里看到C:\ProgramData\Docker之类的路径赶紧把思路切回系统权限。把这两类问题分开能节省大量时间。5. 不让 Token 权限错误反复出现的三个习惯5.1 把 Scope 需求写进仓库文档一个很朴素但极其有效的方法在仓库的 README 或贡献指南里专门写一节“本仓库开发/CD 所需的 GitHub Token 权限”把需要的 scope、是否涉及 SSO、CI 配置里 secret 的名字都列清楚。这样无论是新同事接手还是你两个月后再回来配置都不用靠回忆重新踩一遍。我维护的老项目里就吃过这个亏。当时流水线在 push 之后还要自动更新 tag但仓库文档只写了“需要 token”没写清楚其实需要repo和workflowscope。后来换了个权限更细的 token流水线立刻挂掉。补上文档以后这个问题再也没出现过。5.2 做一次“令牌体检”如果你有不少自动化任务建议每个月花十分钟做一次令牌体检。体检内容很简单列出所有环境变量和 CI secrets 里存在的 GitHub token逐条确认它们对应的权限、过期时间、是否还被使用。对于确认不用的 token直接在 GitHub 后台 revoke别舍不得。GitHub 的后台会对活跃 token 标出最近使用时间你可以在 Personal access tokens 页面看到每个 token 的上次使用记录。如果某个 token 超过 90 天没被使用它很可能已经被遗忘Revoke 掉是更安全的选择。定期清理 token不仅能让错误发生时更容易定位也能降低泄漏风险。5.3 用多账号隔离代替一把梭最后一个习惯是关于 Git 多账号配置。很多人所有仓库都用一个全局用户和同一个 token这会让权限错误变得更难排查——因为你分不清当前请求用的是哪个身份。正确做法是给不同用途的仓库分配不同账号并通过 Git 的 insteadOf 规则区分。比如你有一个私人账号和一个公司账号可以在全局配置里写git config --global url.https://personal-tokengithub.com/.insteadOf https://github.com/注意这种写法和直接拼 token 到 remote URL 一样只适合本地开发不适合公开机器。更稳妥的方案是用 SSH key 区分身份或者用 Git 的 conditional include 按目录加载不同的配置。核心思路是让“哪个仓库用哪个 token”这件事变得透明、可预期而不是依赖一个万能 token 到处捅娄子。我自己的习惯是在任何新环境里配好 Git 之后第一件事不是急着 clone而是跑一遍gh auth status和git config --list --show-origin。这两个命令能让我一眼看出当前这台机器到底在用哪个身份、哪个 token。很多看似复杂的 token 权限错误最后都指向同一个真相不是你不会配 token而是你根本没搞清楚当时在用哪个 token。把这个基本盘抓稳GitHub Token 权限错误对你来说就不再是玄学。