---
title: "测试与故障排查"
description: "使用明确的流程结果定位登录问题，避免把服务可访问误判为 OAuth 全链路正常。"
url: "https://auth.kai.com/docs/troubleshooting"
language: "zh-CN"
version: "Better Auth 1.7.1"
updated: "2026-09-22"
---

# 测试与故障排查

使用明确的流程结果定位登录问题，避免把服务可访问误判为 OAuth 全链路正常。

## 使用 OAuth 测试应用

打开 [/authtest](/authtest)，按页面配置的客户端发起完整授权。它应帮助检查 Discovery、回调、PKCE 兑换和令牌校验。测试页面的能力以实际界面为准；尚未执行的步骤不能记为通过。

选择与控制台登记一致的客户端类型，两种模式均使用 `https://auth.kai.com/authtest/callback`：

- **公共 PKCE**：对应「SPA 或原生公共应用」，只填写 Client ID，浏览器使用 PKCE 兑换令牌。
- **私密 Web**：对应「服务端 Web 应用」，填写 Client ID 和当前有效的客户端密钥。密钥只提交给本站服务端，由服务端执行密钥认证、PKCE 兑换、令牌校验和撤销；不会写入报告或浏览器存储。

私密 Web 测试的密钥及事务在服务端内存中等待授权最多五分钟，回调仅使用一次。流程结束或超时后会尝试撤销本次令牌，并在有时限的清理结束后丢弃密钥。请在同一浏览器完成流程并保持 Cookie 开启。服务重启或发布会结束待处理测试，此时应重新开始；不要重放旧回调。测试报告只短期保留，刷新后可能需要重新测试。

如果回调通过，但兑换阶段提示「客户端认证被拒绝」，优先核对所选类型和当前密钥。PKCE 不替代私密 Web 客户端的密钥认证。

测试客户端必须和其他应用一样登记 redirect URI、scope 与资源权限。不能绕过 consent、关闭 PKCE 或使用生产账号密码作为自动化脚本配置。

## 常见错误

| 现象                        | 优先检查                                                                     |
| --------------------------- | ---------------------------------------------------------------------------- |
| `invalid_target`            | resource 是否准确、已注册启用，客户端是否获准；纯登录可以省略 resource       |
| `invalid_scope`             | 请求 scope 是否被客户端允许，且与资源 scope 有交集                           |
| `invalid_client`            | client ID、类型、secret 和 token endpoint 认证方式是否一致                   |
| 回调被拒绝                  | redirect URI 的协议、主机、端口和路径是否与登记一致                          |
| `invalid_grant`             | 授权码是否重复使用或过期，PKCE verifier 是否匹配，授权是否已撤销             |
| JWT audience 不匹配         | ID token 检查 client ID，业务 access token 检查该 API 的 resource identifier |
| 解析组织角色失败            | `organization_role` 允许 null，`access_version` 是 number                    |
| `/mobile/callback` 返回 400 | 旧端点需要有效 OAuth 响应，裸访问不是登录流程                                |
| Device Code 长期等待        | 用户是否核对并批准，是否遵守 interval 和 slow_down                           |

不要在错误处理里自动删除 resource 后重试业务 API 请求，这会改变授权目标。若仅测试身份登录，应从开始就明确选择不含 resource 的流程。

## 验收清单

1. 正确用户、客户端、回调与 scope 完成登录，ID token 和 UserInfo 的 sub 一致。
2. 错误 state、nonce、issuer、audience 或 PKCE 被拒绝；重复授权码不可使用。
3. 未登记回调、未授权资源、越权 scope 和被禁用应用不能取得访问权。
4. 请求并获准 offline_access 后刷新成功，轮换与撤销行为符合客户端实现。
5. 退出回跳、Auth 会话结束与接入方本地会话失效分别验证。

对线上测试只保留时间、环境、步骤状态和脱敏错误。不要保存完整 code、token、Cookie 或真实个人信息。本文不宣称任何生产测试已经执行。