state_not_found

它是什么？

在 OAuth 回调过程中，Better Auth 期望在传入请求中存在 state 值。 这个 state 最初在 OAuth 流程启动时生成，并发送给提供方。当 提供方重定向回你的应用时，它应该在回调请求中包含相同的 state 值。如果 回调请求中完全缺少 state（查询参数或请求体），我们无法验证流程，请求将被拒绝。

此检查通过确保回调属于发起流程的同一浏览器会话，来防止 CSRF 和重放攻击。

常见原因

• 你直接导航到了 /api/auth/callback，而未先启动 OAuth 流程。
• 反向代理、CDN 或重写规则从回调请求中剥离了查询或请求体参数。
• 授权请求中未向 OAuth 提供方传递 state（自定义或手动流程覆盖了参数）。
• 提供方注册的回调 URL 与实际回调路由不匹配，导致中间重定向并丢弃查询或请求体参数。
• 由于框架路由或中间件的原因，回调到达了一个与预期不同的路由/处理程序，且该处理程序没有读取你预期的查询或请求体。
• 移动/WebView 或深度链接交接打开了一个丢失原始查询字符串的新上下文。

解决方法

通过 Better Auth API 启动流程

始终通过 Better Auth 启动 OAuth 流程，以便正确生成并发送 state。除非你完整镜像了 Better Auth 的参数，否则请避免直接调用回调端点或构造授权 URL。

验证回调 URL 和请求方式

• 确保提供方配置的回调 URL 与应用的 /api/auth/callback 路由完全匹配（包括协议和域名）。
• 大多数提供方通过 GET 和查询参数进行重定向。如果你有自定义处理程序或方法，请确认处理程序读取查询/请求体的方式与提供方的重定向一致。

检查代理、重写和中间件

• 确认任何反向代理（Vercel、Cloudflare、Nginx）和应用级重写都保留了完整的查询字符串（包括 state）。
• 如果有在回调路径上进行重定向或重写的中间件，请确保其完整传递查询和请求体参数。

本地调试

使用浏览器开发者工具 → 网络面板检查回调请求：

• 确认回调 URL 包含 ?state=...（或如果期望存在，则请求体中包含 state）。
• 确认授权请求之前已在同一会话中发送，并且在重定向回之前存在一个 state Cookie。
• 在本地调试期间，在回调处理程序中记录请求查询/请求体字段，以确认服务器实际接收到什么。

需要考虑的边缘情况

• 预览环境和生产域名在发生额外重定向或重写时行为可能不同。
• 移动/WebView 环境和深度链接在传递过程中可能丢失或更改查询参数。