常见问题

常见问题与排错

回调相关

授权页：「回调地址不在白名单内」 redirect_uri 与开发者平台登记值必须逐字符相同——协议、端口、路径、有无尾斜杠都算。 例：登记的是 https://app.example.com/auth/callback，就不能传 .../callback/ 或 http://…。

回跳后拿到 ?error=access_denied 用户在授权页点了「拒绝」。引导重新登录即可。

CORS 相关（纯前端接入）

浏览器控制台报 CORS / preflight 失败 你站点的 origin 不在应用白名单里。公开客户端默认按回调地址的 origin 回落放行——把 https://你的站点 作为回调地址登记，或在应用设置里显式填 cors_origins。

本地 localhost:5500 调不通 http://localhost:xxxx 允许作为回调/来源（非本地 http 不行）。登记时带上端口。

白名单刚改，预检还被拒 预检走模块级缓存，最多 60 秒生效；正文请求不受影响。等一分钟再试。

PKCE 相关

state_mismatch 授权页停留太久（会话标签页的 state 已刷新），或在另一个标签页完成了授权。重新点登录。

code_verifier 校验失败 / 缺少 code_verifier 换了 code 却没有配对的 verifier。典型原因：跳转授权后页面被刷新过，sessionStorage 里的 verifier 丢了。重新走一次 login()。

「GHSSO: 非本地环境必须使用 https」 PKCE 依赖 WebCrypto，只在安全上下文（https 或 localhost）可用。线上页面上 https 是硬要求。

令牌相关

在本地 jwt.io 解出的签名验不过 正常。令牌是 HS256（共享密钥）签名，第三方拿不到密钥，无法本地验签。要确认身份只能 调 GHSSO.me() / 服务端 sso.me(token)。

令牌 7 天就过期 设计如此，没有 refresh_token。过期后重新登录；有后端的站点可按 服务端接入 用 refresh() 续期。

部署相关（Cloudflare）

服务端调 SSO 拿到 HTML 错误页 / JSON 解析失败 十有八九是同 zone 的 Worker 之间用了公网 fetch()，被 Cloudflare 拒（error 1042）。 必须走 Service Binding，见 Workers 接入。SDK 报错文案里也会点名 1042。

平台站点登录转圈 / 报 sso_bad_response 平台的 [[services]] 绑定没生效。访问 /healthz?deep=1 看 sso_probe： json:false 即说明跨 Worker 调用拿到的不是 JSON，去核对 binding 名与 service 名。

换行符 / 编码

中文昵称显示成乱码 确认回调页 HTML 声明了 <meta charset="utf-8">。SDK 与 SSO 全程 UTF-8。

还没解决？接口原始契约见 接口参考；或到 https://www.geekhonize.top 联系我们。