better-auth 是一个综合性的、框架无关的 TypeScript 认证与授权库，提供完整认证方案，并对 Cloudflare D1 提供一等支持，被定位为 Clerk 或 Auth.js 的自托管替代品。
用途与适用场景 资料说明，在以下情况可使用该技能：为 Cloudflare Workers + D1 应用构建认证；需要自托管、与供应商无关的认证方案；从 Clerk 迁移（避免供应商锁定）；从 Auth.js 升级（需要更多功能）；实现带组织/团队的多租户 SaaS；以及需要进阶功能，例如 2FA、passkeys、RBAC、社交登录。
安装方式 核心包安装命令为 npm install better-auth，也提供 pnpm add better-auth 与 yarn add better-auth。数据库适配方面：Cloudflare D1（Workers）需安装 @cloudflare/workers-types；PostgreSQL 需安装 pg drizzle-orm；MySQL/SQLite 使用内置适配器，无需额外包。社交登录为可选，安装命令包括 @better-auth/google、@better-auth/github、@better-auth/microsoft。资料中列出的包版本为 better-auth@1.3.34（最新验证 2025-10-31）。
主要能力 基础认证支持邮箱密码（emailAndPassword），可开启 requireEmailVerification 并配置 sendVerificationEmail。社交登录支持 Google、GitHub、Microsoft 等 provider。客户端提供 createAuthClient 以及 useSession 等能力（资料提示需存在 session endpoint）。服务端提供 auth.handler 处理 /api/auth/* 路由，并提供 auth.getSession(...) 用于在 API 路由与中间件中校验会话，例如 Cloudflare Workers 中返回 401，Next.js middleware 中对 /dashboard 未登录重定向到 /login。 进阶功能以插件形式提供：twoFactor（方法如 totp、sms，包含 enable 与 verify）、organization（含角色与权限，支持创建组织、邀请成员、hasPermission 校验）、multiTenant（tenantIdHeader、isolateData）、rateLimit（window、max、storage 可为 database 或 memory；Cloudflare 下可用 KV 实现分布式限流）。
使用方式示例 资料给出四种模式：Cloudflare Workers + D1（d1Adapter(c.env.DB)、Hono 的 app.all('/api/auth/*')、wrangler.toml 配置 d1_databases 与 vars）；Next.js API Route（new Pool({ connectionString })、[...all]/route.ts 导出 GET/POST 为 auth.handler）；React 客户端集成（authClient.signIn.email、authClient.signIn.social、authClient.signOut、useSession）；受保护 API 路由与中间件（auth.getSession 判断并返回 401 或重定向）。 数据库设置方面，D1 使用 npx better-auth migrate --database d1 生成迁移 SQL，再用 wrangler d1 execute 本地或远程应用；手动 schema 给出 users、sessions、accounts、verification_tokens 等表结构。PostgreSQL 使用 Drizzle schema。社交登录部分给出 Google、GitHub、Microsoft 的 OAuth 凭据创建入口、回调 URL 以及环境变量与配置示例（Microsoft 需 tenantId）。
迁移指南 从 Clerk 迁移的关键差异为：Clerk 是第三方服务、专有、按月收费；better-auth 为自托管、开源、免费。步骤包括导出 Clerk 用户数据并导入数据库、将 Clerk SDK 替换为 better-auth 客户端（如 useUser → useSession）、更新中间件会话校验、配置社交 provider。从 Auth.js（NextAuth）迁移的差异为：Auth.js 功能有限、偏重 callbacks、session 处理方式不一；better-auth 功能更全、基于插件、session 处理一致。步骤包括调整数据库列名（如 emailVerified → email_verified）、替换配置与客户端 hooks（useSession 来源改为 better-auth/client）。
已知问题与解决方案 问题一：D1 最终一致性。会话写入后立即读取可能返回旧数据，表现为登录后下次请求 getSession() 返回 null。解决方式是使用 Cloudflare KV 存储会话以保证强一致性（示例给出 session.storage 的 get/set/delete 实现，使用 SESSIONS_KV）。问题二：SPA 的 CORS。auth API 与前端不同源时出现 CORS 错误，解决方式是在 Worker 中配置 CORS 头（如 Hono 的 cors，设置 origin 与 credentials: true）。资料末尾的 CORS 配置内容未完整给出。
其他限制与说明 资料未提供 better-auth 的收费、价格、具体平台支持范围、性能指标或效果承诺等信息，相关事实暂未提供。