# better-auth - D1 适配器和错误预防指南 **软件包**：better-auth@1.4.0（2025 年 11 月 22 日）**重大更改**：仅限 ESM（v1.4.0）、多团队表更改（v1.3）、D1 需要 Drizzle/Kysely（无直接适配器） ** ** ## ⚠️ 关键：D1 适配器要求 better-auth **没有** 有`d1Adapter()`。您**必须**使用： * **Drizzle ORM** (推荐): `drizzleAdapter(db, {provider: "sqlite" })` * **Kysely** : `new Kysely({ 方言: new D1Dialect({ 数据库: env.DB }) })` 有关详细信息，请参阅下面的问题#1。 ** ** ## v1.4.0 中的新增功能（2025 年 11 月 22 日） **主要特点：** * **无状态会话管理** \- 没有数据库存储的会话 * **仅 ESM 包** ⚠️ 破坏：不再支持 CommonJS * **JWT 密钥轮换** \- 自动密钥轮换以增强安全性 * **SCIM 配置** \- 企业用户配置协议 * **@standard-schema/spec** \- 替换 ZodType 进行验证 * **CaptchaFox 集成** \- 内置验证码支持 * 自动服务器端IP检测 * 基于Cookie的账户数据存储 * 多密钥来源支持 * RP 发起的注销端点 (OIDC) 📚 **文档**： ** ** ## v1.3 中的新增功能（2025 年 7 月） **主要特点：** * **SSO with SAML 2.0** \- 企业单点登录（移至单独的 `@better-auth/sso` 包） * **多团队支持** ⚠️ 重大问题：`teamId` 从成员表中删除，需要新的 `teamMembers` 表 * **附加字段** \- 组织/成员/邀请模型的自定义字段 * 性能改进和错误修复 📚 **文档**： ** ** ## 替代方案：Kysely 适配器模式如果您更喜欢 Kysely 而不是 Drizzle： **文件**：`src/auth.ts` 从“better-auth”导入{betterAuth}；从“kysely”导入{Kysely，CamelCasePlugin}；从“kysely-d1”导入{D1Dialect}；类型环境 = { DB：D1数据库； BETTER_AUTH_SECRET：字符串； // ...其他环境变量 }; 导出函数 createAuth(env: Env) { 返回更好的Auth({ 秘密：env.BETTER_AUTH_SECRET， // Kysely 与 D1Dialect 数据库：{ 数据库：新凯瑟利（{ 方言：新的 D1Dialect({ 数据库：env.DB， }), 插件：[ // 关键：如果将 Drizzle 模式与 Snake_case 结合使用，则为必需新的 CamelCasePlugin(), ], }), 类型：“sqlite”， }, 电子邮件和密码：{ 启用：真， }, // ...其他配置 }); } **为什么选择 CamelCasePlugin？** 如果您的 Drizzle 模式使用 `snake_case` 列名称（例如，`email_verified`），但 better-auth 需要 `camelCase`（例如，`emailVerified`），则 `CamelCasePlugin` 会自动在两者之间转换。 ** ** ## 框架集成 ### TanStack 启动 **⚠️ 关键**：TanStack Start 需要 `reactStartCookies` 插件才能正确处理 cookie 设置。从“better-auth”导入{betterAuth}；从“better-auth/adapters/drizzle”导入{ drizzleAdapter }；从“better-auth/react-start”导入{reactStartCookies}；导出 const auth = betterAuth({ 数据库：drizzleAdapter(db, { 提供者: "sqlite" }), 插件：[ 双因子(), 组织（）， ReactStartCookies(), // ⚠️ 必须是最后一个插件 ], }); **为什么需要**：TanStack Start 使用特殊的 cookie 处理系统。如果没有此插件，“signInEmail()”和“signUpEmail()”等身份验证函数将无法正确设置 cookie，从而导致身份验证失败。 **重要**：`reactStartCookies` 插件**必须是数组中的最后一个插件**。 **API 路由设置** (`/src/routes/api/auth/$.ts`): 从 '@/lib/auth' 导入 { auth } 从 '@tanstack/react-router' 导入 { createFileRoute } 导出 const 路由 = createFileRoute('/api/auth/$')({ 服务器：{ 处理程序：{ GET: ({ request }) => auth.handler(request), POST: ({ request }) => auth.handler(request), }, }, }) 📚 **官方文档**： ** ** ## 可用插件 (v1.3+) Better Auth 提供了高级身份验证功能的插件：插件 |进口|描述 |文档 ---|---|---|--- **OIDC 提供商** | `更好的身份验证/插件` |构建您自己的 OpenID Connect 提供程序（成为其他应用程序的 OAuth 提供程序） | [📚]() **单点登录** | `更好的身份验证/插件` |支持 OIDC、OAuth2 和 SAML 2.0 的企业单点登录 | [📚]() **条纹** | `更好的身份验证/插件` |支付和订阅管理（v1.3+ 稳定）| [📚]() **MCP** | `更好的身份验证/插件` |充当模型上下文协议 (MCP) 客户端的 OAuth 提供者 | [📚]() **博览会** | `better-auth/expo` | React Native/Expo 与安全 cookie 管理集成 | [📚]() ** ** ## API 参考 ### 概述：免费获得什么当您调用“auth.handler()”时，better-auth 会自动在“/api/auth/*”处公开 **80+ 生产就绪的 REST 端点**。每个端点还可以通过“auth.api.*”作为**服务器端方法**用于编程使用。这个双层API系统意味着： * **客户端**（React、Vue、移动应用程序）直接调用 HTTP 端点 * **服务器端代码**（中间件、后台作业）使用 `auth.api.*` 方法 * **零样板** \- 无需手动编写身份验证端点 **节省时间** ：从头开始构建 = ~220 小时。更好的验证 = ~4-8 小时。 **减少 97%。** ** ** ### 自动生成的 HTTP 端点使用“auth.handler()”时，所有端点都会自动在“/api/auth/*”处公开。 #### 核心身份验证端点端点 |方法|描述 ---|---|--- `/注册/电子邮件` |发布 |使用电子邮件/密码注册 `/登录/电子邮件` |发布 |使用电子邮件/密码进行身份验证 `/退出` |发布 |注销用户 `/更改密码` |发布 |更新密码（需要当前密码） `/忘记密码` |发布 |启动密码重置流程 `/重置密码` |发布 |使用令牌完成密码重置 `/发送验证电子邮件` |发布 |发送电子邮件验证链接 `/验证电子邮件` |获取 |使用令牌验证电子邮件 (`?token=`) `/获取会话` |获取 |检索当前会话 `/列表会话` |获取 |获取所有活动用户会话 `/撤销会话` |发布 |结束特定会话 `/撤销其他会话` |发布 |结束除当前会话之外的所有会话 `/撤销会话` |发布 |结束所有用户会话 `/更新用户` |发布 |修改用户个人资料（姓名、图片） `/更改电子邮件` |发布 |更新电子邮件地址 `/设置密码` |发布 |向仅限 OAuth 的帐户添加密码 `/删除用户` |发布 |删除用户帐户 `/列表帐户` |获取 |获取链接的身份验证提供商 `/link-social` |发布 |将 OAuth 提供商连接到帐户 `/取消链接帐户` |发布 |断开提供商的连接 #### 社交 OAuth 端点端点 |方法|描述 ---|---|--- `/登录/社交` |发布 |启动 OAuth 流程（正文中指定的提供商） `/callback/:provider` |获取 | OAuth 回调处理程序（例如“/callback/google”） `/获取访问令牌` |获取 |检索提供商访问令牌 **OAuth 流程示例**： // 客户端发起等待 authClient.signIn.social({ 提供商：“谷歌”，回调URL：“/仪表板”， }); // better-auth 处理重定向到 Google // Google 重定向回 /api/auth/callback/google // better-auth 自动创建会话 ** ** #### 插件端点 ##### 双因素身份验证（2FA 插件）从“better-auth/plugins”导入{twoFactor}；端点 |方法|描述 ---|---|--- `/双因素/启用` |发布 |为用户激活2FA `/双因素/禁用` |发布 |停用 2FA `/two-factor/get-totp-uri` |获取 |获取验证器应用程序的二维码 URI `/two-factor/verify-totp` |发布 |验证来自验证器的 TOTP 代码 `/two-factor/send-otp` |发布 |通过电子邮件发送 OTP `/双因素/验证-otp` |发布 |验证电子邮件 OTP `/双因素/生成备份代码` |发布 |创建恢复代码 `/双因素/验证备份代码` |发布 |使用备份代码登录 `/two-factor/view-backup-codes` |获取 |查看当前备份代码 📚 **文档**： ##### 组织插件（多租户 SaaS）从“better-auth/plugins”导入{组织}； **组织**（10 个端点）：端点 |方法|描述 ---|---|--- `/组织/创建` |发布 |创建组织 `/组织/列表` |获取 |列出用户的组织 `/组织/充实` |获取 |获取完整的组织详细信息 `/组织/更新` |放置 |修改组织 `/组织/删除` |删除 |删除组织 `/组织/check-slug` |获取 |验证段头可用性 `/组织/设置活动` |发布 |设置活跃的组织环境 **成员**（8 个端点）：端点 |方法|描述 ---|---|--- `/组织/列表成员` |获取 |获取组织成员 `/组织/添加成员` |发布 |直接添加会员 `/组织/删除成员` |删除 |删除成员 `/组织/更新成员角色` |放置 |更改会员角色 `/组织/获取活跃成员` |获取 |获取当前会员信息 `/组织/离开` |发布 |离开组织 **邀请**（7 个端点）：端点 |方法|描述 ---|---|--- `/组织/邀请成员` |发布 |发送邀请邮件 `/组织/接受邀请` |发布 |接受邀请 `/组织/拒绝邀请` |发布 |拒绝邀请 `/组织/取消邀请` |发布 |取消待处理的邀请 `/组织/获取邀请` |获取 |获取邀请详情 `/组织/列表邀请` |获取 |列出组织邀请 `/组织/列表用户邀请` |获取 |列出用户的待处理邀请 **团队**（8 个端点）：端点 |方法|描述 ---|---|--- `/组织/创建团队` |发布 |在组织内创建团队 `/组织/列表团队` |获取 |列出组织团队 `/组织/更新团队` |放置 |修改队伍 `/组织/删除团队` |删除 |删除团队 `/组织/set-active-team` |发布 |设置活跃的团队环境 `/组织/列表团队成员` |获取 |列出团队成员 `/组织/添加团队成员` |发布 |添加成员到团队 `/组织/删除团队成员` |删除 |删除团队成员 **权限和角色**（6 个端点）：端点 |方法|描述 ---|---|--- `/组织/有权限` |发布 |检查用户是否有权限 `/组织/创建角色` |发布 |创建自定义角色 `/组织/删除角色` |删除 |删除自定义角色 `/组织/列表角色` |获取 |列出所有角色 `/组织/获取角色` |获取 |获取角色详细信息 `/组织/更新角色` |放置 |修改角色权限 📚 **文档**： ##### 管理插件从“better-auth/plugins”导入{admin}；端点 |方法|描述 ---|---|--- `/admin/创建用户` |发布 |创建用户为管理员 `/admin/list-users` |获取 |列出所有用户（带过滤器/分页） `/admin/set-role` |发布 |分配用户角色 `/admin/设置用户密码` |发布 |更改用户密码 `/admin/更新用户` |放置 |修改用户详细信息 `/admin/删除用户` |删除 |删除用户帐户 `/admin/ban-user` |发布 |禁止用户帐户 `/admin/unban-user` |发布 |解禁用户 `/admin/list-user-sessions` |获取 |获取用户的活动会话 `/admin/撤销用户会话` |删除 |结束特定用户会话 `/admin/撤销用户会话` |删除 |结束所有用户会话 `/admin/模拟用户` |发布 |开始模拟用户 `/admin/stop-impersonating` |发布 |结束模拟会话 📚 **文档**： ##### 其他插件端点 **密钥插件**（5 个端点）- [文档]()： * `/passkey/add`、`/sign-in/passkey`、`/passkey/list`、`/passkey/delete`、`/passkey/update` **Magic Link 插件**（2 个端点）- [文档]()： * `/sign-in/magic-link`, `/magic-link/verify` **用户名插件**（2 个端点）- [文档]()： * `/登录/用户名`, `/用户名/可用` **电话号码插件**（5 个端点）- [文档]()： * `/登录/电话号码`、`/电话号码/send-otp`、`/电话号码/验证`、`/电话号码/请求密码重置`、`/电话号码/重置密码` **电子邮件 OTP 插件**（6 个端点）- [文档]()： * `/email-otp/send-verification-otp`、`/email-otp/check-verification-otp`、`/sign-in/email-otp`、`/email-otp/verify-email`、`/forget-password/email-otp`、`/email-otp/reset-password` **匿名插件**（1 个端点）- [文档]()： * `/登录/匿名` **JWT 插件**（2 个端点）- [文档]()： * `/token`（获取JWT），`/jwks`（用于验证的公钥） **OpenAPI 插件**（2 个端点）- [文档]()： * `/reference` （带有 Scalar UI 的交互式 API 文档） * `/generate-openapi-schema` （获取 JSON 格式的 OpenAPI 规范） ** ** ### 服务器端 API 方法 (`auth.api.*`) 每个 HTTP 端点都有一个相应的服务器端方法。将它们用于： * **服务器端中间件**（保护路由） * **后台作业**（用户清理、通知） * **管理操作**（批量用户管理） * **自定义身份验证流程**（编程会话创建） #### 核心 API 方法 // 认证等待 auth.api.signUpEmail({ 正文：{电子邮件、密码、姓名}，标头：request.headers， }); 等待 auth.api.signInEmail({ body: { 电子邮件、密码、rememberMe: true }, 标头：request.headers， }); 等待 auth.api.signOut({ headers: request.headers }); // 会话管理 const session = wait auth.api.getSession({ headers: request.headers }); 等待 auth.api.listSessions({ headers: request.headers }); 等待 auth.api.revokeSession({ 主体：{令牌：“session_token_here”}，标头：request.headers， }); // 用户管理等待 auth.api.updateUser({ body: { name: "新名称", image: "https://..." }, 标头：request.headers， }); 等待 auth.api.changeEmail({ 正文：{ newEmail：“newemail@example.com” }，标头：request.headers， }); 等待 auth.api.deleteUser({ 主体：{密码：“当前密码”}，标头：request.headers， }); // 账户关联等待 auth.api.linkSocialAccount({ 主体：{提供商：“谷歌”}，标头：request.headers， }); 等待 auth.api.unlinkAccount({ 主体：{providerId：“google”，accountId：“google_123”}，标头：request.headers， }); #### 插件 API 方法 **2FA 插件**： // 启用 2FA const { totpUri, backupCodes } = 等待 auth.api.enableTwoFactor({ 主体：{发行者：“MyApp”}，标头：request.headers， }); // 验证 TOTP 代码等待 auth.api.verifyTOTP({ 主体：{代码：“123456”，trustDevice：true}，标头：request.headers， }); // 生成备份代码 const { backupCodes } = 等待 auth.api.generateBackupCodes({ 标头：request.headers， }); **组织插件**： // 创建组织 const org = 等待 auth.api.createOrganization({ 主体：{名称：“Acme Corp”，slug：“acme”}，标头：request.headers， }); // 添加成员等待 auth.api.addMember({ 正文：{ 用户ID：“user_123”，角色：“管理员”，组织ID：org.id， }, 标头：request.headers， }); // 检查权限 const hasPermission = 等待 auth.api.hasPermission({ 正文：{ 组织ID：org.id，权限：“用户：删除”， }, 标头：request.headers， }); **管理插件**： // 列出用户并分页 const 用户 = 等待 auth.api.listUsers({ 查询：{ 搜索：“约翰”，限制：10，偏移量：0，排序依据：“创建时间”，排序顺序：“描述”， }, 标头：request.headers， }); // 禁止用户等待 auth.api.banUser({ 正文：{ 用户ID：“user_123”，原因：“违反服务条款”，过期时间：新日期（“2025-12-31”）， }, 标头：request.headers， }); // 模拟用户（用于管理员支持） const impersonationSession = 等待 auth.api.impersonateUser({ 正文：{ 用户ID：“user_123”， expiresIn: 3600, // 1 小时 }, 标头：request.headers， }); ** ** ### 何时使用哪个使用案例|使用 HTTP 端点 |使用 `auth.api.*` 方法 ---|---|--- **客户端身份验证** | ✅ 是的 | ❌ 没有 **服务器中间件** | ❌ 否 | ✅ 是的 **后台工作** | ❌ 否 | ✅ 是的 **管理仪表板** | ✅ 是（来自客户）| ✅ 是（来自服务器） **自定义身份验证流程** | ❌ 否 | ✅ 是的 **移动应用程序** | ✅ 是的 | ❌ 没有 **API 路线** | ✅ 是（代理至处理程序）| ✅ 是（直接致电） **示例：受保护的路由中间件** 从“hono”导入{Hono}；从“./auth”导入{createAuth}；从“./db”导入{createDatabase}； const app = new Hono<{ 绑定: Env }>(); // 使用服务器端API的中间件 app.use("/api/protected/*", async (c, next) => { const db = createDatabase(c.env.DB); const auth = createAuth(db, c.env); // 使用服务器端方法 const 会话 = 等待 auth.api.getSession({ 标头：c.req.raw.headers， }); 如果（！会话）{ return c.json({ 错误: "未经授权" }, 401); } // 附加到上下文 c.set("用户", session.user); c.set("会话", session.session); 等待下一个（）； }); // 受保护的路由 app.get("/api/protected/profile", 异步 (c) => { const user = c.get("用户"); 返回 c.json({ 用户 }); }); ** ** ### 发现可用端点使用 **OpenAPI 插件** 查看配置中的所有端点：从“better-auth”导入{betterAuth}；从“better-auth/plugins”导入{ openAPI }；导出 const auth = betterAuth({ 数据库：/* ... */, 插件：[ openAPI(), // 添加 /api/auth/reference 端点 ], }); **交互式文档** ：访问 `http://localhost:8787/api/auth/reference` 这显示了一个**标量 UI**，其中： * ✅ 按功能分组的所有可用端点 * ✅ 带有类型的请求/响应模式 * ✅ 试用功能（在浏览器中测试端点） * ✅ 身份验证要求 * ✅ 多种语言的代码示例 **编程访问**： const schema = 等待 auth.api.generateOpenAPISchema(); console.log(JSON.stringify(schema, null, 2)); // 返回完整的 OpenAPI 3.0 规范 ** ** ### 量化节省时间 **从头开始构建**（手动实现）： * 核心身份验证端点（注册、登录、OAuth、会话）：**40 小时** * 电子邮件验证和密码重置：**10 小时** * 2FA 系统（TOTP、备份代码、电子邮件 OTP）：**20 小时** * 组织（团队、邀请、RBAC）：**60 小时** * 管理面板（用户管理、模拟）：**30 小时** * 测试和调试：**50小时** * 安全加固：**20小时** **总体力劳动**：**~220 小时**（5.5 周全职） **具有更好的身份验证**： * 初始设置：**2-4 小时** * 定制和造型：**2-4 小时** **更好的验证总计**：**4-8 小时** **节省**：**~97% 的开发时间** ** ** ### 要点 better-auth 提供 **80 多个生产就绪端点**，涵盖： * ✅ 核心身份验证（20 个端点） * ✅ 2FA 和无密码（15 个端点） * ✅ 组织和团队（35 个端点） * ✅ 管理员和用户管理（15 个端点） * ✅ 社交 OAuth（自动配置回调） * ✅ OpenAPI 文档（交互式 UI） **您编写零端点代码。**只需配置功能并调用“auth.handler()”。 ** ** ## 已知问题和解决方案 ### 问题 1：“d1Adapter 未导出”错误 **问题**：代码显示 `import { d1Adapter } from 'better-auth/adapters/d1'` 但这不存在。 **症状**：TypeScript 错误或有关缺少导出的运行时错误。 **解决方案**：使用 Drizzle 或 Kysely 代替： // ❌ 错误 - 这不存在从 'better-auth/adapters/d1' 导入 { d1Adapter } 数据库：d1Adapter(env.DB) // ✅ 正确 - 使用毛毛雨从 'better-auth/adapters/drizzle' 导入 { drizzleAdapter } 从 'drizzle-orm/d1' 导入 { drizzle } const db = 毛毛雨(env.DB, { schema }) 数据库：drizzleAdapter(db, { 提供者: "sqlite" }) // ✅ 正确 - 使用 Kysely 从 'kysely' 导入 {Kysely } 从 'kysely-d1' 导入 { D1Dialect } 数据库：{ db: new Kysely({ 方言: new D1Dialect({ 数据库: env.DB }) }), 类型：“sqlite” } **来源**：使用 better-auth + D1 从 4 个生产存储库进行验证 ** ** ### 问题 2：架构生成失败 **问题**：`npx better-auth migrate` 不会创建与 D1 兼容的架构。 **症状**：迁移 SQL 语法错误或不适用于 D1。 **解决方案** ：使用 Drizzle Kit 生成迁移： # 从 Drizzle 模式生成迁移 npx drizzle-kit 生成 # 应用于D1 牧马人 d1 迁移应用 my-app-db --remote **为什么** ：Drizzle Kit 生成与 D1 一起使用的 SQLite 兼容 SQL。 ** ** ### 问题 3：“CamelCase”与“snake_case”列不匹配 **问题**：数据库具有“email_verified”，但更好的身份验证需要“emailVerified”。 **症状**：会话读取失败，用户数据丢失字段。 **解决方案** ：将 `CamelCasePlugin` 与 Kysely 一起使用或正确配置 Drizzle： **与凯瑟莉**：从“kysely”导入{CamelCasePlugin}；新凯瑟利({ 方言: new D1Dialect({ 数据库: env.DB }), plugins: [new CamelCasePlugin()], // 命名约定之间的转换 }) **With Drizzle** ：从一开始就使用驼峰命名法定义模式（如示例所示）。 ** ** ### 第 4 期：D1 最终一致性 **问题**：会话在写入返回陈旧数据后立即读取。 **症状**：用户登录，但“getSession()”在下一个请求时返回 null。 **解决方案**：使用Cloudflare KV进行会话存储（强一致性）：从“better-auth”导入{betterAuth}；导出函数 createAuth(db: 数据库, env: Env) { 返回更好的Auth({ 数据库：drizzleAdapter(db, { 提供者: "sqlite" }), 会话：{ 存储：{ 获取：异步（会话ID）=> { const 会话 = 等待 env.SESSIONS_KV.get(sessionId); 返回会话？ JSON.parse(会话) : null; }, 设置：异步（sessionId，会话，ttl）=> { 等待 env.SESSIONS_KV.put(sessionId, JSON.stringify(session), { 过期时间：ttl， }); }, 删除： async (sessionId) => { 等待 env.SESSIONS_KV.delete(sessionId); }, }, }, }); } **添加到`wrangler.toml`**： [[kv_命名空间]] 绑定=“SESSIONS_KV” id = "你的-kv-命名空间-id" ** ** ### 问题 5：SPA 应用程序的 CORS 错误 **问题**：当身份验证 API 与前端的来源不同时，出现 CORS 错误。 **症状**：浏览器控制台中出现“Access-Control-Allow-Origin”错误。 **解决方案** : 在 Worker 中配置 CORS 标头：从“hono/cors”导入{cors}；应用程序.使用（ “/api/auth/*”，科尔斯（{ 来源：[“https://yourdomain.com”，“http://localhost:3000”]，凭证：true，//允许cookie 允许方法：[“GET”，“POST”，“PUT”，“DELETE”，“OPTIONS”]， }) ）； ** ** ### 问题 6：OAuth 重定向 URI 不匹配 **问题**：社交登录失败并出现“redirect_uri_mismatch”错误。 **症状**：Google/GitHub OAuth 在用户同意后返回错误。 **解决方案**：确保 OAuth 提供程序设置中的完全匹配：提供商设置：https://yourdomain.com/api/auth/callback/google 更好的身份验证网址：https://yourdomain.com/api/auth/callback/google ❌ 错误：http 与 https、尾部斜杠、子域不匹配 ✅ 右：字符与字符完全匹配 **检查更好的身份验证回调 URL** ： // 始终是：{baseURL}/api/auth/callback/{provider} constcallbackURL = `${env.BETTER_AUTH_URL}/api/auth/callback/google`; console.log("在 Google Console 中配置此 URL:",callbackURL); ** ** ### 问题 7：缺少依赖项 **问题**：TypeScript 错误或有关缺少包的运行时错误。 **症状**：`找不到模块'drizzle-orm'`或类似的。 **解决方案**：安装所有必需的软件包： **对于毛毛雨方法**： npm install better-auth drizzle-orm drizzle-kit @cloudflare/workers-types **对于 Kysely 方法**： npm install better-auth kysely kysely-d1 @cloudflare/workers-types ** ** ### 问题 8：电子邮件验证未发送 **问题**：电子邮件验证链接永远不会到达。 **症状**：用户注册，但没有收到电子邮件。 **解决方案**：实现 `sendVerificationEmail` 处理程序：导出 const auth = betterAuth({ 数据库：/* ... */, 电子邮件和密码：{ 启用：真，需要电子邮件验证：true， }, 电子邮件验证：{ sendVerificationEmail: async ({ 用户, url }) => { // 使用您的电子邮件服务（SendGrid、重新发送等）等待发送电子邮件({ 至：用户.电子邮件，主题：“验证您的电子邮件”， html:`

点击下面的链接验证您的电子邮件：

验证电子邮件 `, }); }, 发送注册：真，自动登录后验证：true， expiresIn: 3600, // 1 小时 }, }); **对于 Cloudflare** ：使用 Cloudflare 电子邮件路由或外部服务（重新发送、SendGrid）。 ** ** ### 问题 9：会话过期太快 **问题**：会话意外过期或永不过期。 **症状**：用户意外注销或注销后会话仍然存在。 **解决方案**：配置会话过期：导出 const auth = betterAuth({ 数据库：/* ... */, 会话：{ expiresIn: 60 * 60 * 24 * 7, // 7 天（以秒为单位） updateAge: 60 * 60 * 24, // 每24小时更新一次会话 }, }); ** ** ### 问题 10：社交提供商丢失用户数据 **问题**：社交登录成功，但缺少用户数据（姓名、头像）。 **症状**：登录 Google/GitHub 后，`session.user.name` 为空。 **解决方案**：请求附加范围：社交提供者：{ 谷歌：{ clientId：env.GOOGLE_CLIENT_ID， clientSecret：env.GOOGLE_CLIENT_SECRET， range: ["openid", "email", "profile"], // 包含名称/图像的“个人资料” }, github: { clientId: env.GITHUB_CLIENT_ID, clientSecret：env.GITHUB_CLIENT_SECRET， range: ["user:email", "read:user"], // 'read:user' 获取完整个人资料 }, } ** ** ### 问题 11：Drizzle 架构的 TypeScript 错误 **问题**：TypeScript 抱怨架构类型。 **症状**：`类型“DrizzleD1Database”不可分配给...` **解决方案**：从数据库导出正确的类型： // src/db/index.ts 从“drizzle-orm/d1”导入{ drizzle，输入 DrizzleD1Database }；从“./schema”导入*作为模式；导出类型数据库 = DrizzleD1Database<模式类型>; 导出函数createDatabase（d1：D1Database）：数据库{ 返回细雨（d1，{模式}）； } ** ** ### 问题 12：Wrangler 开发模式不起作用 **问题**：`wrangler dev` 因数据库错误而失败。 **症状**：“未找到数据库”或本地开发中出现迁移错误。 **解决方案**：首先在本地应用迁移： # 将迁移应用到本地 D1 牧马人 d1 迁移应用 my-app-db --local # 然后运行开发服务器牧马人开发者 ** ** ### 问题 13：用户数据更新未反映在 UI 中（使用 TanStack 查询） **问题**：更新用户数据（例如头像、姓名）后，尽管调用了“queryClient.invalidateQueries()”，但“useSession()”中并未出现更改。 **症状**：成功更新后，头像图像或用户个人资料数据显得过时。 TanStack 查询缓存显示更新的数据，但更好的身份验证会话仍然显示旧值。 **根本原因**：better-auth 使用 **nanostores** 进行会话状态管理，而不是 TanStack 查询。调用“queryClient.invalidateQueries()”只会使 React Query 缓存失效，而不会使更好的身份验证纳米存储失效。 **解决方案**：更新用户数据后手动通知nanostore： // 更新用户数据 const { 数据，错误 } = 等待 authClient.updateUser({ 图片：newAvatarUrl，名称：新名称 }) 如果（！错误）{ // 手动使更好的身份验证会话状态无效 authClient.$store.notify('$sessionSignal') // 可选：如果将 React Query 用于其他数据，也会使其无效 queryClient.invalidateQueries({ queryKey: ['用户个人资料'] }) } **何时使用**： * 结合使用 better-auth + TanStack Query * 更新用户个人资料字段（姓名、图像、电子邮件） * 任何修改客户端会话用户数据的操作 **替代**：从 `useSession()` 调用 `refetch()`，但 `$store.notify()` 更直接： const { 数据：会话，重新获取 } = authClient.useSession() // 更新后等待重新获取() **注意**：`$store` 是一个未记录的内部 API。此模式经过生产验证，但在未来更好的验证版本中可能会发生变化。 **来源**：社区发现的模式，经过生产使用验证 ** ** ## 迁移指南 ### 来自职员 **主要区别**： * Clerk：第三方服务 → better-auth：自托管 * Clerk：专有 → better-auth：开源 * 文员：每月费用 → better-auth：免费 **迁移步骤**： 1. **从 Clerk 导出用户数据**（CSV 或 API） 2. **导入到更好的身份验证数据库**： // 迁移脚本 const clerkUsers = 等待 fetchClerkUsers(); for (clerkUsers 的 const clerkUser) { 等待 db.insert(用户).values({ id: 店员用户.id, 电子邮件：clerkUser.email，电子邮件验证：clerkUser.email_verified，姓名： clerkUser.first_name + " " + clerkUser.last_name, 图片：clerkUser.profile_image_url， }); } 3. **用更好的身份验证客户端替换 Clerk SDK**： // 之前（职员）从“@clerk/nextjs”导入{useUser}； const { 用户 } = useUser(); // 之后（更好的验证）从“@/lib/auth-client”导入{authClient}； const { 数据：会话 } = authClient.useSession(); const 用户 = 会话？.user； 4. **更新中间件**以进行会话验证 5. **配置社交提供商**（相同的 OAuth 应用程序，不同的配置） ** ** ### 来自 Auth.js (NextAuth) **主要区别**： * Auth.js：功能有限 → better-auth：全面（2FA、组织等） * Auth.js：重回调 → better-auth：基于插件 * Auth.js：会话处理有所不同 → better-auth：一致 **迁移步骤**： 1. **数据库架构**：Auth.js 和 better-auth 使用类似的架构，但列名不同 2. **更换配置** : // 之前 (Auth.js) 从“next-auth”导入 NextAuth；从“next-auth/providers/google”导入 GoogleProvider；导出默认 NextAuth({ 提供商：[GoogleProvider({ /* ... */ })], }); // 之后（更好的验证）从“better-auth”导入{betterAuth}；导出 const auth = betterAuth({ 社交提供者：{ 谷歌：{ /* ... */ }, }, }); 3. **更新客户端挂钩**： // 之前从“next-auth/react”导入{useSession}； // 之后从“@/lib/auth-client”导入{authClient}； const { 数据：会话 } = authClient.useSession(); ** ** ## 其他资源 ### 官方文档 * **主页** : * **简介** : * **安装** : * **基本用法**： ### 核心概念 * **会话管理**： * **用户和帐户**： * **客户端 SDK** ： * **插件系统** : ### 身份验证方法 * **电子邮件和密码**： * **OAuth 提供商**： ### 插件文档 **核心插件**： * **2FA（双因素）** ： * **组织**： * **管理员** : * **多会话** : * **API 密钥**： * **通用 OAuth** ： **无密码插件**： * **密钥** : * **魔法链接**： * **电子邮件 OTP** ： * **电话号码** : * **匿名** ： **高级插件**： * **用户名** : * **JWT** ： * **OpenAPI** ： * **OIDC 提供商**： * **SSO** ： * **条纹**： * **MCP** ： ### 框架集成 * **TanStack 开始**： * **博览会（React Native）**： ### 社区与支持 * **GitHub**： (22.4k ⭐) * **示例** : * **不和谐**： * **变更日志**： ### 相关文档 * **Drizzle ORM** ： * **凯塞利**： ** ** ## 生产实例 **经过验证的工作 D1 存储库**（全部使用 Drizzle 或 Kysely）： 1. **zpg6/better-auth-cloudflare** \- Drizzle + D1（包括 CLI） 2. **zwily/example-react-router-cloudflare-d1-drizzle-better-auth** \- 毛毛雨 + D1 3. **foxlau/react-router-v7-better-auth** \- 细雨 + D1 4. **matthewlynch/better-auth-react-router-cloudflare-d1** \- Kysely + D1 **没有**使用直接的 `d1Adapter` - 都需要 Drizzle/Kysely。 ** ** ## 版本兼容性 **测试使用**： * `better-auth@1.3.34` * `毛毛雨-orm@0.44.7` *`毛毛雨套件@0.31.6` * `kysely@0.28.8` * `kysely-d1@0.4.0` * `@cloudflare/workers-types@latest` * `hono@4.0.0` * Node.js 18+，Bun 1.0+ **重大更改**：升级时检查更改日志： ** ** **代币效率**： * **无需技能**：约 28,000 个令牌（D1 适配器错误、TanStack Start cookies、nanostore 失效、OAuth 流、API 发现） * **凭借技能**：约 5,600 个代币（专注于错误 + 重大更改 + API 参考） * **节省**：~80%（~22,400 代币） **防止错误**：13 个已记录的问题以及准确的解决方案 **关键值**：D1 适配器要求、v1.4.0/v1.3 重大更改、TanStack Start 修复、nanostore 模式、80+ 端点参考 ** ** **最后验证**：2025 年 11 月 22 日 | **技能版本**：3.0.0 | **更改**：添加了 v1.4.0（仅限 ESM、无状态会话、SCIM）和 v1.3（SSO/SAML、多团队）知识差距。删除了教程/设置（约 700 行）。专注于错误预防+重大更改+API参考。

更好的身份验证

包含技能