BetterAuth身份验证框架 better-auth

---

名称: better-auth 描述: 集成 Better Auth 的技能 - 一个全面的 TypeScript 身份验证框架，适用于 Cloudflare D1、Next.js、Nuxt 和 15+ 框架。在添加身份验证、遇到 D1 适配器错误或实现 OAuth/2FA/RBAC 功能时使用。 关键词: better-auth, 身份验证, cloudflare d1 身份验证, drizzle orm 身份验证, kysely 身份验证, 自托管身份验证, typescript 身份验证, clerk 替代品, auth.js 替代品, 社交登录, oauth 提供商, 会话管理, jwt 令牌, 2fa, 两因素认证, 通行密钥, webauthn, 多租户身份验证, 组织, 团队, rbac, 基于角色的访问, google 身份验证, github 身份验证, microsoft 身份验证, apple 身份验证, 魔法链接, 邮箱密码, better-auth 设置, drizzle d1, kysely d1, 会话序列化错误, cors 身份验证, d1 适配器, nextjs 身份验证, nuxt 身份验证, remix 身份验证, sveltekit 身份验证, expo 身份验证, react native 身份验证, postgresql 身份验证, mongodb 身份验证, mysql 身份验证, stripe 身份验证, api 密钥, sso, saml, scim, 管理仪表板, 后台任务, oauth 2.1, cli 许可证: MIT 元数据: 版本: “2.2.0” 包版本: “1.4.9” 最后验证: “2025-12-26” 预防错误: 15 包含模板: 4 包含参考: 26

better-auth

状态: 生产就绪 最后更新: 2025-12-26 包: better-auth@1.4.9 (仅 ESM) 依赖: Drizzle ORM 或 Kysely (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

⚠️ 关键: D1 适配器要求

better-auth 没有 直接的 d1Adapter()。您 必须 使用以下之一：

1. Drizzle ORM (推荐) - drizzleAdapter()
2. Kysely (替代) - 使用 D1Dialect 的 Kysely 实例

// ❌ 错误 - 这不存在
import { d1Adapter } from 'better-auth/adapters/d1'

// ✅ 正确 - 使用 Drizzle
import { drizzleAdapter } from 'better-auth/adapters/drizzle'
import { drizzle } from 'drizzle-orm/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(),
});

// 查看 references/database-schema.ts 获取完整模式

3. 初始化身份验证 (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。

这是一个新的/空项目吗？
├─ 是 → 新项目设置
│   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 Kit)
│   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 迁移 ✅ 在模式中使用 camelCase 列名

永远不要做

❌ 使用 d1Adapter 或 better-auth migrate 与 D1 ❌ 忘记 CORS 凭据或不匹配 OAuth URL ❌ 使用 snake_case 列而不使用 CamelCasePlugin ❌ 跳过本地迁移或硬编码秘密 ❌ 保留 sendVerificationEmail 未实现

⚠️ v1.4.0+ 破坏性变更

仅 ESM (无 CommonJS):

// package.json 必需
{ "type": "module" }

API 重命名:

• forgetPassword → requestPasswordReset
• POST /account-info → GET /account-info

回调签名:

// v1.3.x: 请求参数
sendVerificationEmail: async ({ user, url, request }) => {}

// 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	基础 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 generate	为 Prisma/Drizzle 生成模式
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 白名单用于跨源请求

常见插件

从 专用路径 导入用于树摇:

import { twoFactor } from "better-auth/plugins/two-factor"
import { organization } from "better-auth/plugins/organization"
import { passkey } from "@better-auth/passkey"  // 单独包

不是 from "better-auth/plugins"。

---

前 5 错误 (查看 references/error-catalog.md 获取所有 15 个)

错误 #1: “d1Adapter 未导出”

问题: 尝试使用不存在的 d1Adapter 解决方案: 使用 drizzleAdapter 或 Kysely 代替 (见上方快速开始)

错误 #2: 模式生成失败

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

错误 #3: CamelCase vs snake_case 不匹配

问题: 数据库使用 email_verified 但 better-auth 期望 emailVerified 解决方案: 在模式中使用 camelCase 或向 Kysely 添加 CamelCasePlugin

错误 #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: 邮箱/密码身份验证

当: 基础身份验证无社交提供商 快速模式:

// 客户端
await authClient.signIn.email({
  email: "user@example.com",
  password: "password123",
});

// 服务器 - 在配置中启用
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+ 更多。 快速模式:

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

// 服务器配置
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: "未经授权" }, 401);
  }

  return c.json({ data: "受保护", 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 当:

• 用户偏好 Kysely 超过 Drizzle
• 用户询问 Kysely 特定实施

加载 references/database-schema.ts 当:

• 用户需要完整的 better-auth 模式带所有表
• 用户询问自定义表或模式扩展
• 用户需要数据库的 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 合规性
• 用户需要 SAML/SSO 带时钟偏移或 OIDC 发现
• 用户询问 about the better-auth CLI 工具
• 用户需要管理员角色权限配置
• 用户询问关于 ctx.isTrustedDomain 或域验证

加载 references/nextjs/README.md 当:

• 用户构建 Next.js 应用带 PostgreSQL (非 Cloudflare D1)
• 用户需要组织和 2FA 示例
• 用户询问 Next.js 特定实施

加载 references/nextjs/postgres-example.ts 当:

• 用户需要完整的 Next.js API 路由实施
• 用户想看到组织 + 2FA 实践
• 用户询问 PostgreSQL 设置带 Drizzle

框架特定设置

加载 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 构建
• 用户需要钩子、加载函数或存储

加载 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/payments.md 当:

• 用户需要 Stripe 或 Polar 集成
• 用户构建订阅或支付功能

---

配置参考

快速配置 (仅 ESM 在 v1.4.0+):

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 - 所有 12 个错误带解决方案和预防清单
• advanced-features.md - 2FA、组织、速率限制、通行密钥、魔法链接、迁移
• configuration-guide.md - 生产配置、环境变量、CORS、速率限制
• framework-comparison.md - better-auth vs Clerk vs Auth.js、迁移路径、TCO
• migration-guide-1.4.0.md - 从 v1.3.x 升级到 v1.4.0+ (ESM、API 变更)
• cloudflare-worker-drizzle.ts - 完整的 Worker 带 Drizzle 身份验证
• cloudflare-worker-kysely.ts - 完整的 Worker 带 Kysely 身份验证
• database-schema.ts - 完整的 better-auth Drizzle 模式
• react-client-hooks.tsx - React 组件带身份验证钩子
• v1.4-features.md - 后台任务、新 OAuth 提供商、SAML/SSO、CLI

框架参考 (references/frameworks/)

• nextjs.md - Next.js App/Pages Router 集成
• nuxt.md - Nuxt 3 带 H3 和组合
• remix.md - Remix loaders、actions、sessions
• sveltekit.md - SvelteKit 钩子和存储
• api-frameworks.md - Express、Fastify、NestJS、Hono
• expo-mobile.md - React Native 和 Expo

数据库参考 (references/databases/)

• postgresql.md - PostgreSQL 带 Drizzle/Prisma、Neon/Supabase
• 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 - 完整的 API 路由带组织、2FA、邮箱验证

客户端集成

创建身份验证客户端 (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>加载中...</div>;
  if (!session) return <div>未认证</div>;

  return (
    <div>
      <p>欢迎, {session.user.email}</p>
      <button onClick={() => authClient.signOut()}>登出</button>
    </div>
  );
}

---

依赖

必需:

• better-auth@^1.4.9 - 核心身份验证框架 (仅 ESM)

选择一个适配器:

• drizzle-orm@^0.44.7 + drizzle-kit@^0.31.7 (推荐)
• kysely@^0.28.8 + @noxharmonium/kysely-d1@^0.4.0 (替代)

可选:

• @cloudflare/workers-types - Workers 的 TypeScript 类型
• hono@^4.0.0 - Web 框架用于路由
• @better-auth/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 设置, 加载适当的框架或数据库参考文件, 或查阅官方文档: 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 vs Clerk vs 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。

---

完整设置清单

• [ ] 验证 ESM 支持 (在 package.json 中 "type": "module") - v1.4.0+ 要求
• [ ] 安装 better-auth@1.4.9+ + Drizzle 或 Kysely
• [ ] 创建 D1 数据库带 wrangler
• [ ] 定义数据库模式带必需表 (user、session、account、verification)
• [ ] 生成并应用迁移到 D1
• [ ] 设置 BETTER_AUTH_SECRET 环境变量
• [ ] 配置 auth 配置中的 baseURL
• [ ] 启用身份验证方法 (emailAndPassword、socialProviders)
• [ ] 配置 CORS 带 credentials: true
• [ ] 在提供商设置中设置 OAuth 回调 URL
• [ ] 测试身份验证路由 (/api/auth/*)
• [ ] 测试登录、注册、会话验证
• [ ] 使用 requestPasswordReset (非 forgetPassword) - v1.4.0+ API
• [ ] 部署到 Cloudflare Workers

---

问题？问题？

1. 检查 references/error-catalog.md 获取所有 15 个错误和解决方案
2. 回顾 references/setup-guide.md 获取完整的 8 步设置
3. 查看 references/advanced-features.md 获取 2FA、组织和更多
4. 检查官方文档: https://better-auth.com
5. 确保您使用 Drizzle 或 Kysely (非不存在的 d1Adapter)