better-auth

better-auth

状态：已可用于生产环境 最后更新：2026-04-08 软件包：[email protected]（仅 ESM） 依赖项：Drizzle ORM 或 Kysely（复杂 D1 使用场景必需；v1.5+ 提供 D1 原生支持）

---

快速开始（5 分钟）

安装

选项 1：Drizzle ORM（推荐）

bun add better-auth drizzle-orm drizzle-kit

选项 2：Kysely

bun add better-auth kysely @noxharmonium/kysely-d1

⚠️ v1.4.0+ 要求

better-auth v1.4.0+ 仅支持 ESM。请确保：

package.json：

{
  "type": "module"
}

从 v1.3.x 升级？ 加载 references/migration-guide-1.4.0.md 从 v1.4.x 升级？ 加载 references/migration-guide-1.5.0.md

⚠️ 关键：D1 适配器要求

v1.5.0+：现在原生支持 D1。直接传入 D1 绑定：

// ✅ SIMPLEST - D1 native (v1.5.0+)
import { betterAuth } from "better-auth";

const auth = betterAuth({
    database: env.DB, // D1 binding, auto-detected
});

对于复杂架构，请使用 Drizzle ORM：

// ✅ RECOMMENDED for complex schemas - Drizzle
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { drizzle } from "drizzle-orm/d1";

const auth = betterAuth({
    database: drizzleAdapter(drizzle(env.DB, { schema }), { provider: "sqlite" }),
});

// ❌ WRONG - This doesn't exist
import { d1Adapter } from 'better-auth/adapters/d1'

最简设置（Cloudflare Workers + Drizzle）

1. 创建 D1 数据库：

wrangler d1 create my-app-db

2. 定义架构（src/db/schema.ts）：

import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";

export const user = sqliteTable("user", {
  id: text().primaryKey(),
  name: text().notNull(),
  email: text().notNull().unique(),
  emailVerified: integer({ mode: "boolean" }).notNull().default(false),
  image: text(),
});

export const session = sqliteTable("session", {
  id: text().primaryKey(),
  userId: text().notNull().references(() => user.id, { onDelete: "cascade" }),
  token: text().notNull(),
  expiresAt: integer({ mode: "timestamp" }).notNull(),
});

// See references/database-schema.ts for complete schema

3. 初始化 Auth（src/auth.ts）：

import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { drizzle } from "drizzle-orm/d1";
import * as schema from "./db/schema";

export function createAuth(env: { DB: D1Database; BETTER_AUTH_SECRET: string }) {
  const db = drizzle(env.DB, { schema });

  return betterAuth({
    baseURL: env.BETTER_AUTH_URL,
    secret: env.BETTER_AUTH_SECRET,
    database: drizzleAdapter(db, { provider: "sqlite" }),
    emailAndPassword: { enabled: true },
  });
}

4. 创建 Worker（src/index.ts）：

import { Hono } from "hono";
import { createAuth } from "./auth";

const app = new Hono<{ Bindings: Env }>();

app.all("/api/auth/*", async (c) => {
  const auth = createAuth(c.env);
  return auth.handler(c.req.raw);
});

export default app;

5. 部署：

bunx drizzle-kit generate
wrangler d1 migrations apply my-app-db --remote
wrangler deploy

---

决策树

有关代码示例和语法，请始终查阅 better-auth.com/docs。

Is this a new/empty project?
├─ YES → New project setup
│   1. Identify framework (Next.js, Nuxt, Workers, etc.)
│   2. Choose database (D1, PostgreSQL, MongoDB, MySQL)
│   3. Install better-auth + Drizzle/Kysely
│   4. Create auth.ts + auth-client.ts
│   5. Set up route handler (see Quick Start above)
│   6. Run migrations (Drizzle Kit for D1)
│   7. Add features via plugins (2FA, organizations, etc.)
│
└─ NO → Does project have existing auth?
    ├─ YES → Migration/enhancement
    │   • Audit current auth for gaps
    │   • Plan incremental migration
    │   • See references/framework-comparison.md for migration guides
    │
    └─ NO → Add auth to existing project
        1. Analyze project structure
        2. Install better-auth + adapter
        3. Create auth config (see Quick Start)
        4. Add route handler to existing routes
        5. Run schema migrations
        6. Integrate into existing pages/components

---

关键规则

必须做到

✅ 使用 better-auth/minimal + 适配器软件包，以获得最小的软件包体积（v1.5+） ✅ CLI 命令使用 npx auth migrate 和 npx auth generate（v1.5+） ✅ 使用 wrangler secret put 设置 BETTER_AUTH_SECRET ✅ 将 CORS 配置为 credentials: true ✅ OAuth 回调 URL 必须完全匹配（末尾不能有斜杠） ✅ 在运行 wrangler dev 前，将迁移应用到本地 D1 ✅ 在架构中使用 camelCase 列名

绝对不要做

❌ 使用 d1Adapter（不存在） ❌ 忘记 CORS credentials 或使用不匹配的 OAuth URL ❌ 未使用 CamelCasePlugin 就使用 snake_case 列名 ❌ 跳过本地迁移或将密钥硬编码 ❌ 不实现 sendVerificationEmail

⚠️ v1.5.0 重大变更

API Key 插件已迁移：

- import { apiKey } from "better-auth/plugins";
+ import { apiKey } from "@better-auth/api-key";

架构：userId → referenceId，新增 configId 字段。

After Hooks：数据库 after-hooks 现在会在事务完成后运行（而非事务内部）。

已移除弃用的 API：Adapter → DBAdapter，已移除 InferUser/InferSession，@better-auth/core/utils 已拆分为子路径导出。

从低于 1.5.0 的版本升级时，请加载 references/migration-guide-1.5.0.md

⚠️ v1.6.0 重大变更

会话新鲜度：freshAge 现在使用 createdAt（而非 updatedAt）。敏感操作可能需要更频繁地重新验证身份。

SAML 安全性：InResponseTo 验证现在默认开启。可使用 saml: { enableInResponseToValidation: false } 关闭。

OIDC Provider 已弃用：请改用 @better-auth/oauth-provider。

v1.5.0 新功能（概览）

• 全新 CLI：npx auth init/migrate/generate/upgrade
• D1 原生支持：直接传入 D1 绑定（无需适配器）
• OAuth 2.1 Provider：@better-auth/oauth-provider（支持 MCP）
• Electron：用于桌面应用的 @better-auth/electron
• i18n：用于错误翻译的 @better-auth/i18n
• 动态 Base URL：支持多域名/预览部署
• 密钥轮换：非破坏性、带版本的密钥
• 测试工具：工厂函数、OTP 捕获、登录助手
• 类型化错误代码：错误响应中包含机器可读的 code

加载 references/v1.5-features.md，查看详细的实现指南。

v1.6.0 新功能（概览）

• OpenTelemetry：分布式追踪（实验性）
• Passkey 预认证：在会话建立前注册 Passkey
• 非阻塞 Scrypt：在 libuv 线程池中进行密码哈希
• 软件包体积缩小 46%：4.2MB → 2.3MB
• 不区分大小写的查询：在适配器查询中使用 mode: "insensitive"

加载 references/v1.6-features.md，查看详细的实现指南。

---

快速参考

环境变量

变量	用途	示例
BETTER_AUTH_SECRET	加密密钥（至少 32 个字符）	生成：openssl rand -base64 32
BETTER_AUTH_URL	基础 URL	https://example.com 或 http://localhost:8787
DATABASE_URL	数据库连接（D1 可选）	PostgreSQL/MySQL 连接字符串

注意：仅当环境变量未设置时，才在配置中定义 baseURL/secret。

CLI 命令（v1.5+）

命令	用途
npx auth init	交互式项目脚手架
npx auth migrate	运行数据库迁移
npx auth generate	生成身份验证架构
npx auth generate --adapter drizzle	生成特定适配器的架构
npx auth upgrade	升级到最新版本
bunx drizzle-kit generate	D1：使用此命令生成 Drizzle 迁移
wrangler d1 migrations apply DB_NAME	D1：使用此命令应用迁移

添加或更改插件后重新运行。

核心配置选项

选项	说明
appName	可选的显示名称
baseURL	仅当未设置 BETTER_AUTH_URL 时使用
basePath	默认为 /api/auth。设为 / 可使用根路径。
secret	仅当未设置 BETTER_AUTH_SECRET 时使用（至少 32 个字符）
database	大多数功能的必需项。D1 使用 drizzleAdapter() 或 Kysely
secondaryStorage	用于会话和速率限制的 Redis/KV
emailAndPassword	设置为 { enabled: true } 以启用
socialProviders	{ google: { clientId, clientSecret }, ... }
plugins	插件数组（从专用路径导入）
trustedOrigins	跨源请求的 CSRF 白名单

常用插件

从专用软件包导入（v1.5+ 拆分）：

import { twoFactor } from "better-auth/plugins/two-factor"
import { organization } from "better-auth/plugins/organization"
import { passkey } from "@better-auth/passkey"          // Separate package
import { apiKey } from "@better-auth/api-key"            // Separate package (v1.5+)
import { sso } from "@better-auth/sso"                   // Separate package (v1.5+)
import { i18n } from "@better-auth/i18n"                 // Separate package (v1.5+)
import { oauthProvider } from "@better-auth/oauth-provider" // Separate package (v1.5+)

核心插件（仍在 better-auth/plugins 中）：twoFactor、organization、admin、anonymous、emailOTP、magicLink、phone-number、multi-session、custom-session。

---

最常见的 5 个错误（全部 15 个错误请参阅 references/error-catalog.md）

错误 #1：“d1Adapter is not exported”

问题：尝试使用不存在的 d1Adapter 解决方案：改用 drizzleAdapter 或 Kysely（参见上方快速入门）

错误 #2：架构生成失败

问题：better-auth migrate 不适用于 D1 解决方案：使用 bunx drizzle-kit generate，然后运行 wrangler d1 migrations apply

错误 #3：驼峰命名与蛇形命名不匹配

问题：数据库使用 email_verified，但 better-auth 需要 emailVerified 解决方案：在架构中使用驼峰命名，或将 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：电子邮件/密码身份验证

适用场景：不使用社交身份提供商的基本身份验证 快速模式：

// Client
await authClient.signIn.email({
  email: "[email protected]",
  password: "password123",
});

// Server - enable in config
emailAndPassword: {
  enabled: true,
  requireEmailVerification: 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 多个。 快速模式：

// Client
await authClient.signIn.social({
  provider: "google",
  callbackURL: "/dashboard",
});

// Server config
socialProviders: {
  google: {
    clientId: env.GOOGLE_CLIENT_ID,
    clientSecret: env.GOOGLE_CLIENT_SECRET,
    scope: ["openid", "email", "profile"],
  },
}

加载：references/setup-guide.md → 第 5 步

用例 3：受保护的 API 路由

适用场景：需要验证用户是否已通过身份验证 快速模式：

app.get("/api/protected", async (c) => {
  const auth = createAuth(c.env);
  const session = await auth.api.getSession({
    headers: c.req.raw.headers,
  });

  if (!session) {
    return c.json({ error: "Unauthorized" }, 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：

• 遇到已记录的 15 种错误中的任何一种
• 用户报告 D1 适配器、架构、CORS 或 OAuth 问题
• 用户询问故障排查或调试
• 用户需要预防检查清单

在以下情况下加载 references/advanced-features.md：

• 用户询问 2FA、通行密钥或魔法链接
• 用户需要组织、团队或 RBAC
• 用户询问速率限制或会话管理
• 用户希望查看从 Clerk 或 Auth.js 迁移的指南
• 用户需要安全最佳实践或性能优化

在以下情况下加载 references/v1.5-features.md：

• 用户询问新的 CLI、MCP 身份验证或 OAuth 2.1 Provider
• 用户需要 Electron 桌面身份验证或 i18n 错误翻译
• 用户询问动态基础 URL 或密钥轮换
• 用户需要 D1 原生支持（无需适配器）或适配器提取
• 用户询问测试工具、按席位计费或类型化错误代码
• 用户需要 Cloudflare D1 原生支持配置

在以下情况下加载 references/v1.6-features.md：

• 用户询问 OpenTelemetry 或分布式追踪
• 用户需要会话前的通行密钥预身份验证注册
• 用户询问不区分大小写的数据库查询
• 用户升级后遇到会话新鲜度问题
• 用户询问 SAML InResponseTo 验证

在以下情况下加载 references/migration-guide-1.5.0.md：

• 用户从低于 1.5.0 的 better-auth 升级到 1.5.0 或更高版本
• 用户遇到 API Key 导入错误（userId → referenceId）
• 用户询问 after 钩子在事务后运行的问题
• 用户遇到 InferUser/InferSession 类型错误
• 用户需要更新 @better-auth/core/utils 导入

在以下情况下加载 references/plugins/sso.md：

• 用户需要使用 OIDC、OAuth2 或 SAML 2.0 的生产级 SSO
• 用户询问 OIDC 发现、SAML SLO 或域名验证
• 用户需要通过 SSO 配置组织
• 用户询问 SAML 安全性（InResponseTo、重放保护、时间戳）
• 用户遇到 SSO 发现错误

在以下情况下加载 references/plugins/test-utils.md：

• 用户正在使用 Better Auth 编写集成测试或 E2E 测试
• 用户需要测试工厂函数（createUser、createOrganization）
• 用户需要经过身份验证的测试会话（login、getAuthHeaders、getCookies）
• 用户需要为验证测试捕获 OTP

在以下情况下加载 references/integrations/electron.md：

• 用户正在使用 Better Auth 构建 Electron 桌面应用
• 用户需要用于桌面应用的系统浏览器 OAuth 流程
• 用户询问深层链接、自定义协议方案
• 用户需要 IPC 桥接或手动令牌交换

在以下情况下加载 references/cloudflare-worker-drizzle.ts：

• 用户需要完整的 Worker 实现示例
• 用户需要可用于生产环境的代码
• 用户希望查看包含受保护路由的完整身份验证流程

在以下情况下加载 references/cloudflare-worker-kysely.ts：

• 用户更倾向于使用 Kysely 而非 Drizzle
• 用户需要 Kysely 专用实现

在以下情况下加载 references/database-schema.ts：

• 用户需要包含所有表的完整 better-auth 架构
• 用户询问自定义表或架构扩展
• 用户需要数据库的 TypeScript 类型

在以下情况下加载 references/react-client-hooks.tsx：

• 用户正在构建 React/Next.js 前端
• 用户需要登录表单、会话钩子或受保护路由
• 用户询问客户端实现 在以下情况下加载 references/configuration-guide.md：
• 用户询问生产环境配置
• 用户需要设置环境变量或 wrangler.toml
• 用户询问动态基础 URL、密钥轮换或 D1 原生支持
• 用户需要配置 CORS、速率限制或 API 密钥
• 用户询问会话配置（deferSessionRefresh、在辅助存储上进行验证）

在以下情况下加载 references/framework-comparison.md：

• 用户询问“better-auth 与 Clerk 相比如何”或“与 Auth.js 相比如何”
• 用户需要帮助选择身份验证框架
• 用户想了解功能对比、迁移建议或成本分析

在以下情况下加载 references/migration-guide-1.4.0.md：

• 用户从低于 1.4.0 的 better-auth 版本升级到 1.4.0 或更高版本
• 用户遇到 forgetPassword 错误或 ESM 问题
• 用户询问破坏性变更或迁移步骤

在以下情况下加载 references/v1.4-features.md：

• 用户询问后台任务或延迟发送邮件
• 用户需要配置 Patreon、Vercel 或 Kick OAuth 提供方
• 用户询问 better-auth CLI 工具
• 用户需要配置管理员角色权限

在以下情况下加载 references/nextjs/README.md：

• 用户使用 PostgreSQL（而非 Cloudflare D1）构建 Next.js 应用
• 用户需要组织和双因素身份验证示例
• 用户询问 Next.js 特定实现

在以下情况下加载 references/nextjs/postgres-example.ts：

• 用户需要完整的 Next.js API 路由实现
• 用户想了解组织和双因素身份验证的实际用法
• 用户询问使用 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 构建应用
• 用户需要 loader/action 模式或会话处理

在以下情况下加载 references/frameworks/sveltekit.md：

• 用户使用 SvelteKit 构建应用
• 用户需要钩子、加载函数或 stores

在以下情况下加载 references/frameworks/api-frameworks.md：

• 用户使用 Express、Fastify、NestJS 或 Hono 构建应用（非 Cloudflare）
• 用户需要中间件或路由配置

在以下情况下加载 references/frameworks/expo-mobile.md：

• 用户使用 React Native 或 Expo 构建应用
• 用户需要 SecureStore、深度链接或移动端身份验证

数据库适配器

在以下情况下加载 references/databases/postgresql.md：

• 用户使用 Drizzle 或 Prisma 搭配 PostgreSQL
• 用户需要配置 Neon、Supabase 或连接池

在以下情况下加载 references/databases/mongodb.md：

• 用户使用 MongoDB
• 用户需要配置 Atlas 或索引

在以下情况下加载 references/databases/mysql.md：

• 用户使用 MySQL 或 PlanetScale
• 用户需要 Vitess 兼容性指导

插件指南

在以下情况下加载 references/plugins/authentication.md：

• 用户需要双因素身份验证、通行密钥（包括预身份验证）、魔法链接、电子邮件 OTP 或匿名用户
• 用户询问增强型身份验证方式

在以下情况下加载 references/plugins/enterprise.md：

• 用户需要组织、SSO/SAML、SCIM 或管理面板
• 用户正在构建多租户或企业级应用

在以下情况下加载 references/plugins/api-tokens.md：

• 用户需要 API 密钥（包括组织所有、多配置）、Bearer 令牌或 JWT
• 用户正在为第三方构建 API 身份验证

在以下情况下加载 references/plugins/payments.md：

• 用户需要集成 Stripe（包括按席位计费）或 Polar
• 用户正在构建订阅或支付功能

在以下情况下加载 references/plugins/sso.md：

• 用户需要在生产环境中使用 OIDC、OAuth2 或 SAML 2.0 配置 SSO
• 用户询问 OIDC 发现、SAML SLO 或域名验证
• 用户需要通过 SSO 配置组织

在以下情况下加载 references/plugins/test-utils.md：

• 用户正在编写集成测试或端到端测试
• 用户需要测试工厂、OTP 捕获或已验证身份的会话

集成指南

在以下情况下加载 references/integrations/electron.md：

• 用户正在使用 Better Auth 构建 Electron 桌面应用
• 用户需要系统浏览器 OAuth、深度链接和 IPC 桥接

---

配置参考

快速配置（v1.4.0+ 仅支持 ESM）：

export const auth = betterAuth({
  baseURL: env.BETTER_AUTH_URL,
  secret: env.BETTER_AUTH_SECRET,
  database: drizzleAdapter(db, { provider: "sqlite" }),
});

在以下情况下加载 references/configuration-guide.md：

• 使用电子邮件/密码和社交提供商进行生产环境配置
• wrangler.toml 设置和环境变量
• 会话配置、CORS 设置和 ESM 要求
• 速率限制、API 密钥（v1.4.0+）和故障排查

---

使用捆绑资源

参考资料（references/）

• setup-guide.md - 完整的 8 步设置流程（D1 → Drizzle → 部署）
• error-catalog.md - 全部 15 种错误及其解决方案和预防检查清单
• advanced-features.md - 双重身份验证、组织、速率限制、通行密钥、魔法链接、迁移
• configuration-guide.md - 生产环境配置、动态基础 URL、密钥轮换、D1 原生支持
• framework-comparison.md - better-auth 与 Clerk、Auth.js 的对比，迁移路径，总拥有成本
• migration-guide-1.4.0.md - 从 v1.3.x 升级到 v1.4.0+（ESM、API 变更）
• migration-guide-1.5.0.md - 从 v1.4.x 升级到 v1.5.0+（API 密钥、适配器导入、钩子）
• v1.4-features.md - 后台任务、新 OAuth 提供商、SAML/SSO、CLI
• v1.5-features.md - 新 CLI、OAuth 2.1 提供商、Electron、国际化、D1 原生支持、密钥轮换
• v1.6-features.md - OpenTelemetry、通行密钥预认证、非阻塞 scrypt
• cloudflare-worker-drizzle.ts - 完整的 Drizzle 身份验证 Worker
• cloudflare-worker-kysely.ts - 完整的 Kysely 身份验证 Worker
• database-schema.ts - 完整的 better-auth Drizzle 架构
• react-client-hooks.tsx - 带身份验证钩子的 React 组件

框架参考（references/frameworks/）

• nextjs.md - Next.js App/Pages Router 集成
• nuxt.md - 使用 H3 和组合式函数的 Nuxt 3
• remix.md - Remix 加载器、操作和会话
• sveltekit.md - SvelteKit 钩子和存储
• api-frameworks.md - Express、Fastify、NestJS、Hono
• expo-mobile.md - React Native 和 Expo

数据库参考（references/databases/）

• postgresql.md - 使用 Drizzle/Prisma 的 PostgreSQL、Neon/Supabase
• mongodb.md - MongoDB 适配器和 Atlas
• mysql.md - MySQL 和 PlanetScale

插件参考（references/plugins/）

• authentication.md - 双重身份验证、通行密钥（包括预认证）、魔法链接、电子邮件 OTP、匿名身份验证
• enterprise.md - 组织、SSO、SCIM、管理
• api-tokens.md - API 密钥（包括组织所有、多配置）、Bearer 令牌、JWT
• payments.md - Stripe、Polar 集成
• sso.md - 生产环境 SSO：OIDC 发现、SAML SLO、域名验证、安全
• test-utils.md - 测试辅助工具：工厂函数、OTP 捕获、登录、Vitest/Playwright

集成参考（references/integrations/）

• electron.md - Electron 桌面身份验证：系统浏览器 OAuth、IPC 桥接、深度链接

Next.js 示例（references/nextjs/）

• README.md - Next.js + PostgreSQL 设置指南（非 D1）
• postgres-example.ts - 包含组织、双重身份验证、电子邮件验证的完整 API 路由

客户端集成

创建身份验证客户端（src/lib/auth-client.ts）：

import { createAuthClient } from "better-auth/client";

export const authClient = createAuthClient({
  baseURL: import.meta.env.VITE_API_URL || "http://localhost:8787",
});

在 React 中使用：

import { authClient } from "@/lib/auth-client";

export function UserProfile() {
  const { data: session, isPending } = authClient.useSession();

  if (isPending) return <div>Loading...</div>;
  if (!session) return <div>Not authenticated</div>;

  return (
    <div>
      <p>Welcome, {session.user.email}</p>
      <button onClick={() => authClient.signOut()}>Sign Out</button>
    </div>
  );
}

---

依赖项

必需：

• better-auth@^1.6.0 - 核心身份验证框架（仅支持 ESM）

选择一个适配器（v1.5+ 中使用 D1 原生支持时可选）：

• drizzle-orm@^0.45.2 + drizzle-kit@^0.31.10（复杂架构推荐使用）
• kysely@^0.28.8 + @noxharmonium/kysely-d1@^0.4.0（替代方案）
• @better-auth/drizzle-adapter + better-auth/minimal（包体积最小，v1.5+）

可选：

• @cloudflare/workers-types - Workers 的 TypeScript 类型
• hono@^4.12.12 - 用于路由的 Web 框架
• @better-auth/passkey - Passkey/WebAuthn 插件
• @better-auth/api-key - 支持组织的 API 密钥身份验证
• @better-auth/sso - 用于生产环境的 SSO/SAML/OIDC 插件
• @better-auth/electron - Electron 桌面身份验证
• @better-auth/i18n - 错误消息翻译
• @better-auth/oauth-provider - OAuth 2.1 授权服务

---

超越 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 等。

其他插件：匿名身份验证、Email OTP、JWT、多会话、OAuth 2.1 Provider、测试工具、SCIM、支付集成（Stripe、Polar）、设备授权。

对于非 Cloudflare 配置，请加载相应的框架或数据库参考文件，或参阅官方文档：https://better-auth.com/docs

---

官方文档

• better-auth 文档：https://better-auth.com
• GitHub：https://github.com/better-auth/better-auth (22.4k ⭐)
• 示例：https://github.com/better-auth/better-auth/tree/main/examples
• Drizzle 文档：https://orm.drizzle.team/docs/get-started-sqlite
• Kysely 文档：https://kysely.dev/
• Discord：https://discord.gg/better-auth

---

框架对比

加载 references/framework-comparison.md，了解以下内容：

• 完整功能对比：better-auth 与 Clerk、Auth.js
• v1.4.0+ 新功能（数据库联接、无状态会话、API 密钥）
• 迁移路径、成本分析和性能基准测试
• 按使用场景提供的建议和 5 年 TCO

---

生产环境示例

已验证可运行的代码库（均使用 Drizzle 或 Kysely）：

1. zwily/example-react-router-cloudflare-d1-drizzle-better-auth - Drizzle
2. matthewlynch/better-auth-react-router-cloudflare-d1 - Kysely
3. foxlau/react-router-v7-better-auth - Drizzle
4. zpg6/better-auth-cloudflare - Drizzle（包含 CLI）

注意：请检查各代码库使用的 better-auth 版本。使用 v1.3.x 的代码库需要迁移到 v1.4.0+（参见 references/migration-guide-1.4.0.md）。没有代码库使用直接的 d1Adapter - 均需要 Drizzle/Kysely。

---

安全安装

安装身份验证软件包时，请遵循供应链安全最佳实践 — 身份验证库是供应链攻击的重要目标：

• 阻止安装后脚本 — npm config set ignore-scripts true（或使用 Bun：默认已禁用）
• 冷却期 — 等待 7 天，让社区审查新版本的软件包
• 安装前审计 — 运行 socket package score npm <pkg>，或使用 socket npm install <pkg> 检查软件包

加载 dependency-upgrade 技能，了解完整的安全配置，包括 Socket CLI 集成、冷却期设置、锁文件验证和 CI 强制执行。

完整设置检查清单

• 已验证 ESM 支持（在 package.json 中设置 "type": "module"）——需要 v1.4.0+
• 已安装 [email protected]+（原生支持 D1）或 + Drizzle/Kysely
• 已使用 wrangler 创建 D1 数据库
• 已定义数据库架构（或使用无需架构的原生 D1）
• 已生成并应用迁移到 D1
• 已设置 BETTER_AUTH_SECRET 环境变量
• 已在身份验证配置中设置 baseURL（或为预览环境设置动态 base URL）
• 已启用身份验证方式（emailAndPassword、socialProviders）
• 已将 CORS 配置为 credentials: true
• 已在提供商设置中设置 OAuth 回调 URL
• 已测试身份验证路由（/api/auth/*）
• 已测试登录、注册和会话验证
• 使用 requestPasswordReset（而不是 forgetPassword）——v1.4.0+ API
• 使用 npx auth CLI（而不是 @better-auth/cli）——v1.5.0+
• 使用 @better-auth/api-key（而不是 better-auth/plugins）处理 API 密钥——v1.5.0+
• 已部署到 Cloudflare Workers

---

有疑问？遇到问题？

1. 查看 references/error-catalog.md，了解全部 15 个错误及其解决方案
2. 查看 references/setup-guide.md，了解完整的 8 步设置流程
3. 查看 references/advanced-features.md，了解双因素身份验证、组织等功能
4. 查看官方文档：https://better-auth.com
5. 确保使用 Drizzle 或 Kysely（不存在 d1Adapter）