# 更好的认证 **状态**：生产就绪 **最后更新**：2025-12-26 **软件包**：`better-auth@1.4.9`（仅限 ESM） **依赖项**：Drizzle ORM 或 Kysely（D1 所需） ** ** ## 快速入门（5 分钟） ### 安装 **选项 1：Drizzle ORM（推荐）** 面包添加更好的授权毛毛雨-orm毛毛雨套件 **选项 2：凯瑟利** 包子添加更好的身份验证 kysely @noxharmium/kysely-d1 ### ⚠️ v1.4.0+ 要求 better-auth v1.4.0+ 是**仅限 ESM**。确保： **包.json**： { “类型”：“模块” } **从 v1.3.x 升级？** 加载 `references/migration-guide-1.4.0.md` ### ⚠️ 关键：D1 适配器要求 better-auth **没有** 有直接的“d1Adapter()”。您**必须**使用： 1. **Drizzle ORM**（推荐）- `drizzleAdapter()` 2. **Kysely**（替代）- 使用 D1Dialect 的 Kysely 实例 // ❌ 错误 - 这不存在从 'better-auth/adapters/d1' 导入 { d1Adapter } // ✅ 正确 - 使用毛毛雨从 'better-auth/adapters/drizzle' 导入 { drizzleAdapter } 从 'drizzle-orm/d1' 导入 { drizzle } ### 最小设置（Cloudflare Workers + Drizzle） **1\.创建 D1 数据库：** 牧马人 d1 创建 my-app-db **2\.定义架构**（`src/db/schema.ts`）：从“drizzle-orm/sqlite-core”导入{整数，sqliteTable，文本}；导出 const user = sqliteTable("用户", { id: 文本().primaryKey(), 名称：text().notNull(), 电子邮件：text().notNull().unique(), emailVerified: 整数({ mode: "boolean" }).notNull().default(false), 图像：文本（）， }); 导出 const 会话 = sqliteTable("会话", { id: 文本().primaryKey(), userId: text().notNull().references(() => user.id, { onDelete: "cascade" }), 标记：text().notNull(), expiresAt: integer({ mode: "timestamp" }).notNull(), }); // 有关完整模式，请参阅references/database-schema.ts **3\.初始化 Auth** (`src/auth.ts`)：从“better-auth”导入{betterAuth}；从“better-auth/adapters/drizzle”导入{ drizzleAdapter }；从“drizzle-orm/d1”导入{ drizzle }；从“./db/schema”导入*作为模式；导出函数 createAuth(env: { DB: D1Database; BETTER_AUTH_SECRET: string }) { const db = drizzle(env.DB, { schema }); 返回更好的Auth({ 基本URL：env.BETTER_AUTH_URL，秘密：env.BETTER_AUTH_SECRET，数据库：drizzleAdapter(db, { 提供者: "sqlite" }), emailAndPassword: { 启用: true }, }); } **4\.创建 Worker** (`src/index.ts`)：从“hono”导入{Hono}；从“./auth”导入{createAuth}； const app = new Hono<{ 绑定: Env }>(); app.all("/api/auth/*", 异步 (c) => { const auth = createAuth(c.env); 返回 auth.handler(c.req.raw); }); 导出默认应用程序； **5\.部署：** Bunx drizzle-kit 生成牧马人 d1 迁移应用 my-app-db --remote 牧马人部署 ** ** ## 决策树 **有关代码示例和语法，请参阅[better-auth.com/docs]()。** 这是一个新的/空的项目吗？ ├─ 是 → 新项目设置 │ 1. 识别框架（Next.js、Nuxt、Workers 等） │ 2.选择数据库（D1、PostgreSQL、MongoDB、MySQL） │ 3. 安装 better-auth + Drizzle/Kysely │ 4.创建auth.ts + auth-client.ts │ 5. 设置路由处理程序（参见上面的快速入门） │ 6. 运行迁移（D1 的 Drizzle 套件） │ 7. 通过插件添加功能（2FA、组织等） │ └─ 否 → 项目是否有现有的授权？ ├─ 是 → 迁移/增强 │ • 审核当前身份验证是否存在缺陷 │ • 规划增量迁移 │ • 请参阅references/framework-comparison.md 了解迁移指南 │ └─ 否 → 添加授权到现有项目 1.分析项目结构 2.安装better-auth+适配器 3. 创建身份验证配置（请参阅快速入门） 4. 将路由处理程序添加到现有路由 5. 运行架构迁移 6. 集成到现有页面/组件中 ** ** ## 关键规则 ### 必须做 ✅ 使用 Drizzle/Kysely 适配器（d1Adapter 不存在） ✅ 使用 Drizzle Kit 进行迁移（不是 `better-auth migrate`） ✅ 通过 `wrangler Secret put` 设置 BETTER_AUTH_SECRET ✅ 使用 `credentials: true` 配置 CORS ✅ 完全匹配 OAuth 回调 URL（无尾部斜杠） ✅ 在 `wrangler dev` 之前将迁移应用到本地 D1 ✅ 使用驼峰命名法模式中的列名 ### 永远不要这样做 ❌ 将 `d1Adapter` 或 `better-auth migrate` 与 D1 配合使用 ❌ 忘记 CORS 凭据或不匹配 OAuth URL ❌ 使用不带 CamelCasePlugin 的 Snake_case 列 ❌ 跳过本地迁移或硬编码机密 ❌ 不实现 sendVerificationEmail ### ⚠️ v1.4.0+ 重大变更 **仅限 ESM**（无 CommonJS）： // 需要 package.json {“类型”：“模块”} **API 重命名**： * `忘记密码` → `请求密码重置` * POST `/account-info` → GET `/account-info` **回调签名**： // v1.3.x: 请求参数 sendVerificationEmail: async ({ 用户, url, 请求 }) => {} // v1.4.0+: ctx 参数 sendVerificationEmail: async ({ user, url, ctx }) => {} **从<1.4.0升级时加载`references/migration-guide-1.4.0.md` ### v1.4.4-1.4.8 中的新增功能 **自 v1.4.3 以来的主要新增内容**： * **后台任务** (v1.4.8)：全局 `backgroundTasks` 配置以推迟电子邮件发送 * **新的 OAuth 提供程序** ：带有刷新令牌的 Patreon (v1.4.8)、Vercel (v1.4.3)、Kick (v1.4.6) * **OAuth 2.1 插件** (v1.4.8)：符合标准的 OAuth 实施 * **CLI 工具** (v1.4.4)：带有项目脚手架的“better-auth” CLI * **SAML/SSO**：时钟偏差验证 (v1.4.7)、InResponseTo、OIDC 发现 * **管理员权限** (v1.4.7)：具有精细用户更新权限的管理员角色 * **ctx.isTrustedDomain** (v1.4.6)：域验证助手 **加载`references/v1.4-features.md`以获取详细的实施指南。** ** ** ## 快速参考 ### 环境变量变量|目的|示例 ---|---|--- `BETTER_AUTH_SECRET` |加密秘密（最少 32 个字符）|生成：`openssl rand -base64 32` `BETTER_AUTH_URL` |基本网址 | `https://example.com` 或 `http://localhost:8787` `DATABASE_URL` |数据库连接（D1 可选）| PostgreSQL/MySQL 连接字符串 **注意**：如果未设置环境变量，则仅在配置中定义 `baseURL`/`secret`。 ### CLI 命令命令|目的 ---|--- `npx @better-auth/cli@latest migrate` |应用架构（仅限内置 Kysely 适配器） `npx @better-auth/cli@latest 生成` |为 Prisma/Drizzle 生成架构 `bunx drizzle-kit 生成` | **D1：使用此**生成 Drizzle 迁移 `wrangler d1 迁移应用 DB_NAME` | **D1：使用此**来应用迁移 **添加/更改插件后重新运行。** ### 核心配置选项选项 |注释 ---|--- `应用程序名称` |可选的显示名称 `baseURL` |仅当未设置“BETTER_AUTH_URL”时 `基本路径` |默认`/api/auth`。设置“/”为根。 `秘密` |仅当未设置“BETTER_AUTH_SECRET”时（最少 32 个字符） `数据库` | **对于大多数功能来说是必需的**。对 D1 使用 `drizzleAdapter()` 或 Kysely `辅助存储` | Redis/KV 用于会话和速率限制 `电子邮件和密码` | `{enabled: true }` 激活 `社会提供者` | `{ 谷歌: { clientId, clientSecret }, ... }` `插件` |插件数组（从专用路径导入） `trustedOrigins` |跨域请求的CSRF白名单 ### 常用插件从 **专用路径** 导入以进行树摇动：从“better-auth/plugins/two-factor”导入{twoFactor} 从“better-auth/plugins/organization”导入{组织} import { passkey } from "@better-auth/passkey" // 单独的包 **不是**`来自“better-auth/plugins”`。 ** ** ## 前 5 个错误（请参阅references/error-catalog.md 了解所有 15 个错误） ### 错误 #1：“d1Adapter 未导出” **问题**：尝试使用不存在的 `d1Adapter` **解决方案**：使用 `drizzleAdapter` 或 Kysely（请参阅上面的快速入门） ### 错误 #2：架构生成失败 **问题**：“better-auth migrate”不适用于 D1 **解决方案**：使用“bunx drizzle-kit generated”，然后使用“wrangler d1 迁移应用” ### 错误 #3：CamelCase 与 Snake_case 不匹配 **问题**：数据库使用`email_verified`，但更好的身份验证需要`emailVerified` **解决方案**：在架构中使用camelCase或将`CamelCasePlugin`添加到Kysely ### 错误 #4：CORS 错误 **问题**：“Access-Control-Allow-Origin”错误，未发送 cookie **解决方案**：使用“credentials: true”和正确的来源配置 CORS ### 错误 #5：OAuth 重定向 URI 不匹配 **问题**：社交登录因“redirect_uri_mismatch”而失败 **解决方案**：确保完全匹配：`https://yourdomain.com/api/auth/callback/google` **加载`references/error-catalog.md`以获取所有 15 个错误以及详细的解决方案。** ** ** ## 常见用例 ### 用例 1：电子邮件/密码身份验证 **何时**：无需社交提供商的基本身份验证**快速模式**： // 客户端等待 authClient.signIn.email({ 电子邮件：“user@example.com”，密码：“密码123”， }); // 服务器 - 在配置中启用电子邮件和密码：{ 启用：真，需要电子邮件验证：true， } **加载**：`references/setup-guide.md` → 步骤 5 ### 用例 2：社交身份验证（45+ 提供商） **何时**：允许用户使用社交帐户登录 **支持**：Google、GitHub、Microsoft、Apple、Discord、TikTok、Twitch、Spotify、LinkedIn、Slack、Reddit、Facebook、Twitter/X、Patreon、Vercel、Kick 等 30 多个。 **快速模式**： // 客户端等待 authClient.signIn.social({ 提供商：“谷歌”，回调URL：“/仪表板”， }); // 服务器配置社交提供者：{ 谷歌：{ clientId：env.GOOGLE_CLIENT_ID， clientSecret：env.GOOGLE_CLIENT_SECRET，范围：[“openid”，“电子邮件”，“个人资料”]， }, } **加载**：`references/setup-guide.md` → 步骤 5 ### 用例 3：受保护的 API 路由 **何时**：需要验证用户是否已通过身份验证**快速模式**： app.get("/api/protected", 异步 (c) => { const auth = createAuth(c.env); const 会话 = 等待 auth.api.getSession({ 标头：c.req.raw.headers， }); 如果（！会话）{ return c.json({ 错误: "未经授权" }, 401); } return c.json({ data: "protected", user: session.user }); }); **加载**：`references/cloudflare-worker-drizzle.ts` ### 用例 4：组织多租户 **何时**：与团队/组织一起构建 SaaS **加载**：`references/advanced-features.md` → 组织和团队 ### 用例 5：双因素身份验证 **何时**：需要 2FA/TOTP 的额外安全性 **加载**：`references/advanced-features.md` → 双因素身份验证 ** ** ## 何时加载参考文献 **加载`references/setup-guide.md`时**： * 用户需要完整的 8 步设置演练 * 用户询问 Kysely 适配器替代方案 * 用户需要迁移或部署方面的帮助 * 用户询问 wrangler.toml 配置 **加载`references/error-catalog.md`时**： * 遇到 12 个记录错误中的任何一个 * 用户报告 D1 适配器、架构、CORS 或 OAuth 问题 * 用户询问故障排除或调试 * 用户需求预防清单 **加载`references/advanced-features.md`时**： * 用户询问 2FA、密钥或魔术链接 * 用户需要组织、团队或RBAC * 用户询问速率限制或会话管理 * 用户需要来自 Clerk 或 Auth.js 的迁移指南 * 用户需要安全最佳实践或性能优化 **加载`references/cloudflare-worker-drizzle.ts`时**： * 用户需要完整的Worker实现示例 * 用户请求生产就绪代码 * 用户希望看到受保护路由的完整身份验证流程 **加载`references/cloudflare-worker-kysely.ts`时**： * 与 Drizzle 相比，用户更喜欢 Kysely * 用户请求特定于 Kysely 的实现 **加载`references/database-schema.ts`时**： * 用户需要包含所有表的完整的更好的身份验证模式 * 用户询问自定义表或模式扩展 * 用户需要数据库的 TypeScript 类型 **加载`references/react-client-hooks.tsx`时**： * 用户构建 React/Next.js 前端 * 用户需要登录表单、会话挂钩或受保护的路由 * 用户询问客户端实现 **加载`references/configuration-guide.md`时**： * 用户询问生产配置 * 用户需要环境变量设置或wrangler.toml * 用户询问会话配置或 ESM 设置 * 用户需要 CORS 配置、速率限制或 API 密钥 * 用户询问配置问题的故障排除 **加载`references/framework-comparison.md`时**： * 用户询问“better-auth vs Clerk”或“vs Auth.js” * 用户需要帮助选择身份验证框架 * 用户想要功能比较、迁移建议或成本分析 * 用户询问 v1.4.0+ 新功能（数据库连接、无状态会话） **加载`references/migration-guide-1.4.0.md`时**： * 用户从 better-auth <1.4.0 升级到 1.4.0+ * 用户遇到 `forgetPassword` 错误或 ESM 问题 * 用户询问重大更改或迁移步骤 * 用户需要迁移回调函数或API端点 **加载`references/v1.4-features.md`时**： * 用户询问后台任务或延迟电子邮件发送 * 用户需要 Patreon、Vercel 或 Kick OAuth 提供商设置 * 用户询问 OAuth 2.1 合规性 * 用户需要具有时钟偏差或 OIDC 发现的 SAML/SSO * 用户询问更好的身份验证 CLI 工具 * 用户需要admin角色权限配置 * 用户询问 ctx.isTrustedDomain 或域验证 **加载`references/nextjs/README.md`时**： * 用户使用 PostgreSQL（不是 Cloudflare D1）构建 Next.js 应用程序 * 用户需求组织和2FA示例 * 用户询问 Next.js 特定的实现 **加载`references/nextjs/postgres-example.ts`时**： * 用户需要完整的 Next.js API 路由实现 * 用户希望看到组织+ 2FA 的实践 * 用户请求使用 Drizzle 设置 PostgreSQL ### 特定于框架的设置 **加载`references/frameworks/nextjs.md`时**： * 使用 Next.js（App Router 或 Pages Router）构建用户 * 用户需要中间件、服务器组件或 API 路由 **加载`references/frameworks/nuxt.md`时**： * 使用 Nuxt 3 进行用户构建 * 用户需要 H3 处理程序、可组合项或服务器路由 **加载`references/frameworks/remix.md`时**： * 使用 Remix 建立用户 * 用户需要加载器/操作模式或会话处理 **加载`references/frameworks/sveltekit.md`时**： * 使用 SvelteKit 构建用户 * 用户需要钩子、加载函数或存储 **加载`references/frameworks/api-frameworks.md`时**： * 使用 Express、Fastify、NestJS 或 Hono（非 Cloudflare）进行用户构建 * 用户需要中间件或路由配置 **加载`references/frameworks/expo-mobile.md`时**： * 用户构建 React Native 或 Expo 应用程序 * 用户需要 SecureStore、深度链接或移动身份验证 ### 数据库适配器 **加载`references/databases/postgresql.md`时**： * 使用 PostgreSQL 和 Drizzle 或 Prisma 的用户 * 用户需要 Neon、Supabase 或连接池设置 **加载`references/databases/mongodb.md`时**： * 使用 MongoDB 的用户 * 用户需要Atlas设置或索引 **加载`references/databases/mysql.md`时**： * 使用 MySQL 或 PlanetScale 的用户 * 用户需要Vitess兼容性指导 ### 插件指南 **加载`references/plugins/authentication.md`时**： * 用户需要 2FA、密钥、魔术链接、电子邮件 OTP 或匿名用户 * 用户询问增强的身份验证方法 **加载`references/plugins/enterprise.md`时**： * 用户需要组织、SSO/SAML、SCIM 或管理仪表板 * 用户构建多租户或企业应用程序 **加载`references/plugins/api-tokens.md`时**： * 用户需要 API 密钥、不记名令牌、JWT 或 OIDC 提供商 * 用户构建第三方API认证 **加载`references/plugins/ payment.md`时**： * 用户需要 Stripe 或 Polar 集成 * 用户建立订阅或支付功能 ** ** ## 配置参考 **快速配置**（仅限 v1.4.0+ 中的 ESM）：导出 const auth = betterAuth({ 基本URL：env.BETTER_AUTH_URL，秘密：env.BETTER_AUTH_SECRET，数据库：drizzleAdapter(db, { 提供者: "sqlite" }), }); **加载`references/configuration-guide.md`用于**： * 带有电子邮件/密码和社交提供商的生产配置 * wrangler.toml 设置和环境变量 * 会话配置、CORS 设置和 ESM 要求 * 速率限制、API 密钥 (v1.4.0+) 和故障排除 ** ** ## 使用捆绑资源 ### 参考文献（参考文献/） * **setup-guide.md** \- 完成 8 步设置（D1 → Drizzle → 部署） * **error-catalog.md** \- 所有 12 个错误及其解决方案和预防清单 * **advanced-features.md** \- 2FA、组织、速率限制、密钥、魔术链接、迁移 * **configuration-guide.md** \- 生产配置、环境变量、CORS、速率限制 * **framework-comparison.md** \- better-auth 与 Clerk 与 Auth.js、迁移路径、TCO * **migration-guide-1.4.0.md** \- 从 v1.3.x 升级到 v1.4.0+（ESM、API 更改） * **cloudflare-worker-drizzle.ts** \- 具有 Drizzle 身份验证的完整 Worker * **cloudflare-worker-kysely.ts** \- 具有 Kysely 身份验证的完整 Worker * **database-schema.ts** \- 完整的更好的身份验证 Drizzle 架构 * **react-client-hooks.tsx** \- 使用 auth hooks 响应组件 * **v1.4-features.md** \- 后台任务、新的 OAuth 提供程序、SAML/SSO、CLI ### 框架参考（references/frameworks/） * **nextjs.md** \- Next.js 应用程序/页面路由器集成 * **nuxt.md** \- Nuxt 3 与 H3 和可组合项 * **remix.md** \- 重新混合加载器、操作、会话 * **sveltekit.md** \- SvelteKit 挂钩和商店 * **api-frameworks.md** \- Express、Fastify、NestJS、Hono * **expo-mobile.md** \- React Native 和 Expo ### 数据库参考（references/databases/） * **postgresql.md** \- 带有 Drizzle/Prisma、Neon/Supabase 的 PostgreSQL * **mongodb.md** \- MongoDB 适配器和 Atlas * **mysql.md** \- MySQL 和 PlanetScale ### 插件参考 (references/plugins/) * **authentication.md** \- 2FA、密钥、魔术链接、电子邮件 OTP、匿名 * **enterprise.md** \- 组织、SSO、SCIM、管理员 * **api-tokens.md** \- API 密钥、不记名令牌、JWT、OIDC * ** Payments.md** \- Stripe、Polar 集成 ### Next.js 示例 (references/nextjs/) * **README.md** \- Next.js + PostgreSQL 设置指南（不是 D1） * **postgres-example.ts** \- 与组织、2FA、电子邮件验证的完整 API 路线 ### 客户端集成 **创建身份验证客户端** (`src/lib/auth-client.ts`): 从“better-auth/client”导入{createAuthClient}；导出 const authClient = createAuthClient({ 基本URL: import.meta.env.VITE_API_URL || “http://localhost:8787”， }); **在 React 中使用**：从“@/lib/auth-client”导入{authClient}；导出函数 UserProfile() { const { data: session, isPending } = authClient.useSession(); if (isPending) return

正在加载...

; if (!session) return

未验证

; 返回（

欢迎，{session.user.email}

）； } ** ** ## 依赖关系 **必填**： * `better-auth@^1.4.9` \- 核心身份验证框架（仅限 ESM） **选择一个适配器**： * `drizzle-orm@^0.44.7` \+ `drizzle-kit@^0.31.7` (推荐) * `kysely@^0.28.8` \+ `@noxharmium/kysely-d1@^0.4.0` （替代） **可选**： * `@cloudflare/workers-types` \- Workers 的 TypeScript 类型 * `hono@^4.0.0` \- 用于路由的 Web 框架 * `@better-auth/passkey` \- Passkey 插件（v1.4.0+，单独的包） * `@better-auth/api-key` \- API 密钥身份验证 (v1.4.0+) ** ** ## 超越 Cloudflare D1 该技能重点关注 **Cloudflare Workers + D1**。 better-auth 还支持： **框架**（总共 18 个）：Next.js、Nuxt、Remix、SvelteKit、Astro、Express、NestJS、Fastify、Elysia、Expo 等。 **数据库**（9 个适配器）：PostgreSQL、MongoDB、MySQL、Prisma、MS SQL 等。 **其他插件**：匿名身份验证、电子邮件 OTP、JWT、多会话、OIDC 提供商、支付集成（Stripe、Polar）。 **对于非 Cloudflare 设置**，加载适当的框架或数据库参考文件，或查阅官方文档： ** ** ## 官方文档 * **better-auth 文档**： * **GitHub**： (22.4k ⭐) * **示例** : * **Drizzle 文档**： * **Kysely 文档**： * **不和谐**： ** ** ## 框架比较 **加载`references/framework-comparison.md`用于**： * 完整的功能比较：better-auth vs Clerk vs Auth.js * v1.4.0+ 新功能（数据库连接、无状态会话、API 密钥） * 迁移路径、成本分析和性能基准 * 按使用案例和 5 年 TCO 提出的建议 ** ** ## 生产实例 **经过验证的工作存储库**（全部使用 Drizzle 或 Kysely）： 1. **zwily/example-react-router-cloudflare-d1-drizzle-better-auth** \- 细雨 2. **matthewlynch/better-auth-react-router-cloudflare-d1** \- Kysely 3. **foxlau/react-router-v7-better-auth** \-毛毛雨 4. **zpg6/better-auth-cloudflare** \- Drizzle（包括 CLI） **注意**：检查每个存储库的更好的验证版本。 v1.3.x 上的存储库需要 v1.4.0+ 迁移（请参阅“references/migration-guide-1.4.0.md”）。没有一个使用直接的 `d1Adapter` - 都需要 Drizzle/Kysely。 ** ** ## 完整设置清单 * 已验证 ESM 支持（package.json 中的“type”：“module”）- 需要 v1.4.0+ * 安装了 better-auth@1.4.9+ + Drizzle 或 Kysely * 使用wrangler创建D1数据库 * 定义数据库模式与所需的表（用户、会话、帐户、验证） * 生成迁移并将其应用到 D1 * 设置BETTER_AUTH_SECRET环境变量 * 在auth配置中配置baseURL * 启用身份验证方法（emailAndPassword、socialProviders） * 使用凭据配置 CORS：true * 在提供商设置中设置 OAuth 回调 URL * 测试的身份验证路由 (/api/auth/*) * 测试登录、注册、会话验证 * 使用 requestPasswordReset（不是忘记密码）- v1.4.0+ API * 部署到 Cloudflare Workers ** ** **有问题吗？有问题吗？** 1. 检查 `references/error-catalog.md` 中所有 15 个错误和解决方案 2. 查看 `references/setup-guide.md` 以了解完整的 8 步设置 3. 有关 2FA、组织等，请参阅“references/advanced-features.md” 4.查看官方文档： 5. 确保您使用 **Drizzle 或 Kysely**（不是不存在的 d1Adapter）

更好的身份验证

包含技能