GitHub OAuth App 多个 redirect URI 怎么迁移：token refresh 与回归核对

OAuth 登录一旦从单一回调地址扩展到多个环境，最容易出问题的地方不是授权跳转页，而是 redirect URI 精确匹配、旧令牌下线和回滚路径的适配。GitHub 在 2026 年 8 月 14 日的更新日志中公布了 OAuth App 的多 redirect URI 与 token refresh 相关能力升级，迁移时可以把测试环境、预发布环境和生产环境的配置拆开管理，但仍要把每个登记的回调地址当成独立安全边界逐一核对。

稳妥迁移顺序是：先登记并验证所有 redirect URI，再小范围启用 refresh token，确认回调、过期、撤销和回滚逻辑都可测后，最后扩大用户覆盖范围。

GitHub OAuth App 这次更新改变了什么

过去一个 OAuth App 通常只能配置一个回调地址，开发、预发布和生产环境只能靠手动改配置或者拆分多个应用来避开回调冲突。这次 GitHub 的更新允许单个 OAuth App 配置多个 redirect URI，同时支持 OAuth App 主动设置 access token 过期规则和 refresh token 相关逻辑。它减少了多环境之间的重复配置成本，但也让回调地址清单、令牌生命周期管理和撤销策略的优先级变得更高。

官方更新日志只说明能力范围和使用方向，具体可见的配置开关、账号覆盖范围以及界面字段都以 GitHub 当前 OAuth App 设置页的展示为准。不要把“支持配置多个地址”误读成可以使用通配符或者模糊匹配规则。

先把 redirect URI 按环境整理成核对清单

迁移前先在代码仓库里全局搜索授权请求和回调路由，整理出所有真实在用的回调地址。这份从代码侧梳理出来的清单，比直接在 GitHub 设置页手动追加地址要可靠得多：

地址的协议、主机、端口、路径和尾部斜杠都要作为独立字段逐一核对。应用发起授权时传入的 redirect_uri 必须和后台已登记的值完全一致；如果应用自身是根据请求头动态拼接回调地址，先修正代理层的可信 host 配置，不要用“删除尾斜杠再做比较”的取巧方式掩盖逻辑错误。

token refresh 怎么接入才不会打断现有登录流程

建议先完全保留旧的 access token 读取逻辑，在令牌存储结构里新增 refresh token、过期时间和刷新锁字段。接口请求收到令牌过期响应时，仅允许同一用户的一个请求发起刷新操作，其他请求等待同一刷新结果返回，避免并发刷新操作把刚生成的新令牌互相覆盖。

if tokenExpired(accessToken) {
    token = refreshOnce(refreshToken)
    saveToken(token.accessToken, token.refreshToken, token.expiresAt)
}
callGitHub(token.accessToken)

上面的代码只是流程示意。真实业务实现还要处理 refresh token 轮换逻辑：如果刷新接口响应返回了新的 refresh token，必须原子替换本地存储的旧值；刷新失败时直接清理本地会话，引导用户重新走授权流程。不要把 refresh token 打印到日志、存进前端 localStorage 或者上报到错误追踪平台。

上线前用四组用例做回归核对

1. 正常回调：分别从开发、预发布和生产环境入口发起登录，确认 state 校验、code 换 token 和最终生成的业务会话都落在对应环境内。
2. 非法地址拦截：把 redirect_uri 改成错误端口、HTTP 协议或者相似域名，确认授权流程不会把授权 code 下发给错误的跳转入口。
3. 令牌过期场景：手动缩短测试环境的令牌有效期，验证单次刷新、并发请求合并和 refresh token 轮换逻辑都符合预期。
4. 撤销恢复场景：手动撤销 refresh token 后再次访问业务接口，确认系统会自动清理本地旧会话并跳转回授权页，不会进入无限重试的死循环。

如果这四组用例还没有做自动化覆盖，至少要把请求 URL、响应状态和服务端对应事件都记录到测试记录里。尤其要注意存量旧用户：他们手里可能只有旧格式的 token，不能因为新字段为空就被系统误判为永久有效。

和拆分多个 OAuth App 的方案相比该怎么选

多个 redirect URI 的方案适合同一产品、同一权限模型下的多环境部署场景；拆分多个独立 OAuth App 的方案则更适合租户隔离、权限范围不一致或者需要完全分离审计数据的场景。前者配置集中，误配之后的影响面更大；后者边界清晰，但 client_id、密钥和回调地址的维护成本会明显上升。

生产系统对权限隔离要求更高时，不要为了少维护一份配置就强行共用同一个 OAuth App。先核对不同环境的 scope 是否完全相同，再评估撤销、审计和故障恢复是否需要独立处理。

常见问题

多个 redirect URI 能不能使用通配符？

不要默认支持。按精确登记值做配置和校验，具体支持规则以 GitHub OAuth App 当前设置页和官方文档说明为准。

启用 refresh token 之后还要继续保存 access token 吗？

要保存。refresh token 是用来获取新 access token 的凭证，实际调用 GitHub API 仍需要使用 access token，同时还要配套记录它的过期时间。

刷新失败时应该一直重试吗？

不应该。碰到无效、已撤销或者轮换失败的 refresh token，要直接停止重试、清理本地旧会话并引导用户重新授权。

开发和生产可以共用一个 OAuth App 吗？

技术上可以实现，但要先评估权限、审计和误回调的风险。生产数据和权限边界差异较大的时候，拆分独立应用更容易控制故障影响面。

这次 GitHub OAuth App 更新真正省下的只是多环境回调配置的重复劳动，没有降低安全核对的要求。把地址清单、令牌轮换、并发刷新和撤销恢复都纳入回归测试范围，整个迁移才算真正完成。