# 更好的认证技能 ## 概述 **better-auth** 是一个全面的、与框架无关的 TypeScript 身份验证和授权库。它提供了完整的身份验证解决方案，并对 Cloudflare D1 提供一流的支持，使其成为 Clerk 或 Auth.js 的出色自托管替代方案。 **在以下情况下使用此技能**： * 为 Cloudflare Workers + D1 应用程序构建身份验证 * 需要一个自托管、独立于供应商的身份验证解决方案 * 从 Clerk 迁移（避免供应商锁定） * 从 Auth.js 升级（需要更多功能） * 与组织/团队实施多租户 SaaS * 需要高级功能：2FA、密钥、RBAC、社交身份验证 **软件包**：`better-auth@1.3.34`（最新验证时间为 2025 年 10 月 31 日） ** ** ## 安装 ### 核心包 npm 安装更好的身份验证 # 或 pnpm 添加更好的身份验证 # 或纱线添加更好的认证 ### 数据库适配器 **对于 Cloudflare D1**（工作人员）： npm install @cloudflare/workers-types **对于 PostgreSQL** ： npm 安装 pg drizzle-orm **对于 MySQL/SQLite** ：内置适配器，无需额外的软件包。 ### 社会提供者（可选） npm 安装@better-auth/google npm 安装@better-auth/github npm install @better-auth/microsoft ** ** ## 快速启动模式 ### 模式 1：Cloudflare Workers + D1 **使用时间**：使用 D1 数据库在 Cloudflare Workers 上构建 API **文件**：`src/worker.ts` 从 'better-auth' 导入 { betterAuth } 从 'better-auth/adapters/d1' 导入 { d1Adapter } 从 'hono' 导入 { Hono } 类型环境 = { 数据库：D1数据库 BETTER_AUTH_SECRET：字符串 GOOGLE_CLIENT_ID：字符串 GOOGLE_CLIENT_SECRET：字符串 } const app = new Hono<{ 绑定: Env }>() // 身份验证路由处理程序 app.all('/api/auth/*', 异步 (c) => { 常量身份验证 = betterAuth({ 数据库：d1Adapter(c.env.DB), 秘密：c.env.BETTER_AUTH_SECRET， // 基本的认证方法电子邮件和密码：{ 启用：真，要求电子邮件验证：true }, // 社交提供者社交提供者：{ 谷歌：{ clientId：c.env.GOOGLE_CLIENT_ID，客户端秘密：c.env.GOOGLE_CLIENT_SECRET } } }) 返回 auth.handler(c.req.raw) }) 导出默认应用程序 **牧马人.toml**：名称 =“我的应用程序” 主要=“src/worker.ts” 兼容性_日期=“2024-01-01” [[d1_数据库]] 绑定=“DB” 数据库名称=“我的应用程序数据库” 数据库ID =“您的数据库ID” [变量] # 这里的公共变量 # 秘密（使用：牧马人秘密放入 BETTER_AUTH_SECRET） # - BETTER_AUTH_SECRET # - GOOGLE_CLIENT_ID # - GOOGLE_CLIENT_SECRET **设置 D1 数据库** : # 创建数据库牧马人 d1 创建 my-app-db # 从 better-auth 生成迁移 SQL npx better-auth migrate --database d1 # 应用迁移牧马人 d1 执行 my-app-db --remote --file migrations/0001_initial.sql ** ** ### 模式 2：Next.js API 路由 **使用时间**：使用 PostgreSQL 或 D1 构建传统的 Next.js 应用程序 **文件**：`src/lib/auth.ts` 从 'better-auth' 导入 { betterAuth } 从 'pg' 导入 { Pool } 导出 const auth = betterAuth({ 数据库：新池（{ 连接字符串：process.env.DATABASE_URL }), 秘密：process.env.BETTER_AUTH_SECRET！，电子邮件和密码：{ 启用：真，需要电子邮件验证：true， sendVerificationEmail: async ({ 用户, url }) => { // 发送带有验证链接的电子邮件等待发送电子邮件({ 至：用户.电子邮件，主题：“验证您的电子邮件”， html: `点击此处进行验证` }) } }, 社交提供者：{ 谷歌：{ clientId：process.env.GOOGLE_CLIENT_ID！， clientSecret：process.env.GOOGLE_CLIENT_SECRET！ }, github: { clientId: process.env.GITHUB_CLIENT_ID!, clientSecret：process.env.GITHUB_CLIENT_SECRET！ } }, // 通过插件的高级功能插件：[ 双因子(), 组织（），速率限制() ] }) **文件** : `src/app/api/auth/[...all]/route.ts` 从 '@/lib/auth' 导入 { auth } 导出 const GET = auth.handler 导出 const POST = auth.handler ** ** ### 模式 3：React 客户端集成 **使用时**：需要客户端身份验证状态和操作 **文件**：`src/lib/auth-client.ts` 从 'better-auth/client' 导入 { createAuthClient } 导出 const authClient = createAuthClient({ 基本URL：process.env.NEXT_PUBLIC_API_URL || 'http://localhost:3000' }) **文件**：`src/components/LoginForm.tsx` “使用客户端” 从 '@/lib/auth-client' 导入 { authClient } 从 'react' 导入 { useState } 导出函数LoginForm() { const [电子邮件，setEmail] = useState('') const [密码, setPassword] = useState('') const handleSubmit = async (e: React.FormEvent) => { e.preventDefault() const { 数据，错误 } = 等待 authClient.signIn.email({ 电子邮件，密码 }) 如果（错误）{ console.error('登录失败：', error) 返回 } // 重定向或更新UI window.location.href = '/仪表板' } const handleGoogleSignIn = async () => { 等待 authClient.signIn.social({ 提供商：“谷歌”，回调URL：'/仪表板' }) } 返回（

<输入类型=“电子邮件” 值={电子邮件} onChange={(e) => setEmail(e.target.value)} 占位符=“电子邮件” /> <输入类型=“密码” 值={密码} onChange={(e) => setPassword(e.target.value)} 占位符=“密码” /> <按钮类型=“按钮”onClick={handleGoogleSignIn}> 使用 Google 登录） } **使用 React Hook** （如果您有会话端点）： “使用客户端” 从 'better-auth/client' 导入 { useSession } 导出函数 UserProfile() { const { 数据：会话，isPending } = useSession() if (isPending) return

正在加载...

if (!session) return

未验证

返回（

欢迎，{session.user.email}

） } ** ** ### 模式 4：受保护的 API 路由（中间件） **使用时** ：需要验证 API 路由中的会话 **Cloudflare 工作人员**：从 'better-auth' 导入 { betterAuth } 从 'better-auth/adapters/d1' 导入 { d1Adapter } app.get('/api/protected', async (c) => { 常量身份验证 = betterAuth({ 数据库：d1Adapter(c.env.DB), 秘密：c.env.BETTER_AUTH_SECRET }) const 会话 = 等待 auth.getSession(c.req.raw) 如果（！会话）{ 返回 c.json({ 错误: '未经授权' }, 401) } 返回 c.json({ 消息：“受保护的数据”，用户：会话.用户 }) }) **Next.js 中间件**： // 中间件.ts 从 'next/server' 导入 { NextRequest, NextResponse } 从 '@/lib/auth' 导入 { auth } 导出异步函数中间件（请求：NextRequest）{ const 会话 = 等待 auth.getSession(请求) if (!session && request.nextUrl.pathname.startsWith('/dashboard')) { 返回 NextResponse.redirect(new URL('/login', request.url)) } 返回 NextResponse.next() } 导出常量配置= { 匹配器：['/仪表板/:路径*'] } ** ** ## 高级功能 ### 双因素身份验证 (2FA) 从 'better-auth' 导入 { betterAuth } 从'better-auth/plugins'导入{twoFactor} 导出 const auth = betterAuth({ 数据库：/* ... */, 插件：[ 双因子({ methods: ['totp', 'sms'], // 基于时间或短信发行人：“MyApp” }) ] }) **客户**： // 为用户启用2FA const { 数据，错误 } = 等待 authClient.twoFactor.enable({ 方法：'顶' }) // 验证码等待 authClient.twoFactor.verify({ 代码：'123456' }) ** ** ### 组织和团队从 'better-auth' 导入 { betterAuth } 从“better-auth/plugins”导入{组织} 导出 const auth = betterAuth({ 数据库：/* ... */, 插件：[ 组织（{ 角色：['所有者'、'管理员'、'成员']、权限：{ 管理员：['读'，'写'，'删除']，成员：['读'] } }) ] }) **客户**： // 创建组织等待 authClient.organization.create({ 名称：“Acme 公司”， slug: 'acme' }) // 邀请会员等待 authClient.organization.inviteMember({ 组织 ID: 'org_123', 电子邮件：'user@example.com'，角色：“成员” }) // 检查权限 const canDelete = 等待 authClient.organization.hasPermission({ 组织 ID: 'org_123', 权限：“删除” }) ** ** ### 多租户 SaaS 从 'better-auth' 导入 { betterAuth } 从 'better-auth/plugins' 导入 { multiTenant } 导出 const auth = betterAuth({ 数据库：/* ... */, 插件：[ 多租户({ tenantIdHeader: 'x-租户-id', isolateData: true // 确保租户数据隔离 }) ] }) ** ** ### 速率限制从 'better-auth' 导入 { betterAuth } 从'better-auth/plugins'导入{rateLimit} 导出 const auth = betterAuth({ 数据库：/* ... */, 插件：[ 速率限制({ 窗口: 60, // 60 秒 max: 5, // 每个窗口 5 个请求 storage: '数据库' // 或 '内存' }) ] }) **对于 Cloudflare** ：使用 KV 进行分布式速率限制：从'better-auth/plugins'导入{rateLimit} 插件：[ 速率限制({ 窗户：60，最大：5，存储：{ 获取：异步（键）=> { 返回等待c.env.RATE_LIMIT_KV.get(key) }, 设置：异步（键，值，ttl）=> { 等待 c.env.RATE_LIMIT_KV.put(key, value, {expirationTtl: ttl }) } } }) ] ** ** ## 数据库设置 ### D1 架构迁移 # 生成迁移 npx better-auth migrate --database d1 # 这将创建：migrations/0001_initial.sql **应用迁移**： # 本地牧马人 d1 执行 my-app-db --local --file migrations/0001_initial.sql # 生产牧马人 d1 执行 my-app-db --remote --file migrations/0001_initial.sql **手动架构**（如果需要）： -- 更好的认证核心表创建表用户（ id 文本主键，电子邮件文本唯一不为空， emailVerified INTEGER DEFAULT 0, 名称文本，图像文本，创建于 INTEGER NOT NULL，更新为 INTEGER NOT NULL ）；创建表会话（ id 文本主键，用户 ID 文本不为空，到期时间为 INTEGER NOT NULL， ip 地址文本，用户代理文本，删除级联时外键（userId）引用用户（id））；创建表帐户（ id 文本主键，用户 ID 文本不为空，提供者文本不为空，提供者帐户 ID 文本不为空，访问令牌文本，刷新令牌文本，到期时间为 INTEGER，删除级联时外键（userId）引用用户（id））；创建表验证令牌（标识符文本不为空，令牌文本不为空，过期 INTEGER NOT NULL, 主键（标识符、令牌））； -- 插件的附加表（组织、2FA 等） ** ** ### PostgreSQL 与毛毛雨 **文件**：`src/db/schema.ts` 从 'drizzle-orm/pg-core' 导入 { pgTable, text, timestamp, boolean } 导出常量用户 = pgTable('用户', { id: text('id').primaryKey(), 电子邮件：文本（'电子邮件'）.unique（）.notNull（）， emailVerified: boolean('email_verified').default(false), 名称：文本（'名称'），图像：文本（'图像'）， createAt: 时间戳('created_at').notNull().defaultNow(), updateAt: 时间戳('updated_at').notNull().defaultNow() }) // ...其他表 **设置**：从 'drizzle-orm/postgres-js' 导入 { drizzle } 从 'postgres' 导入 postgres 从 'better-auth' 导入 { betterAuth } const client = postgres(process.env.DATABASE_URL!) const db = 细雨（客户端）导出 const auth = betterAuth({ 数据库：数据库， // ... }) ** ** ## 社交提供商设置 ### 谷歌 OAuth 1. **创建 OAuth 凭证** : 2. **授权重定向 URI** : `https://yourdomain.com/api/auth/callback/google` 3. **环境变量**： GOOGLE_CLIENT_ID=您的客户 ID GOOGLE_CLIENT_SECRET=您的客户秘密 **配置**：社交提供者：{ 谷歌：{ clientId：process.env.GOOGLE_CLIENT_ID！， clientSecret：process.env.GOOGLE_CLIENT_SECRET！， range: ['email', 'profile'] // 可选 } } ** ** ### GitHub OAuth 1. **创建 OAuth 应用程序** : 2. **授权回调URL** : `https://yourdomain.com/api/auth/callback/github` 3. **环境变量**： GITHUB_CLIENT_ID=您的客户 ID GITHUB_CLIENT_SECRET=您的客户秘密 **配置**：社交提供者：{ github: { clientId: process.env.GITHUB_CLIENT_ID!, clientSecret：process.env.GITHUB_CLIENT_SECRET！ } } ** ** ### 微软 OAuth npm install @better-auth/microsoft 1. **Azure 门户**： → 应用程序注册 2. **重定向 URI** ：`https://yourdomain.com/api/auth/callback/microsoft` 3. **环境变量**： MICROSOFT_CLIENT_ID=您的客户端 ID MICROSOFT_CLIENT_SECRET=您的客户端秘密 MICROSOFT_TENANT_ID=common # 或您的租户 ID **配置**：从“@better-auth/microsoft”导入 { microsoft } 社交提供者：{ 微软：微软({ clientId：process.env.MICROSOFT_CLIENT_ID！， clientSecret：process.env.MICROSOFT_CLIENT_SECRET！，租户ID：process.env.MICROSOFT_TENANT_ID！ }) } ** ** ## 迁移指南 ### 来自职员 **主要区别**： * Clerk：第三方服务 → better-auth：自托管 * Clerk：专有 → better-auth：开源 * 文员：每月费用 → better-auth：免费 **迁移步骤**： 1. **从 Clerk 导出用户数据**（CSV 或 API） 2. **导入到更好的身份验证数据库**： // 迁移脚本 const clerkUsers = 等待 fetchClerkUsers() for (clerkUsers 的 const clerkUser) { 等待 db.insert(users).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() // 之后（更好的验证）从 'better-auth/client' 导入 { useSession } const { 数据：会话 } = useSession() 常量用户=会话？.用户 4. **更新中间件**以进行会话验证 5. **配置社交提供商**（相同的 OAuth 应用程序，不同的配置） ** ** ### 来自 Auth.js (NextAuth) **主要区别**： * Auth.js：功能有限 → better-auth：全面（2FA、组织等） * Auth.js：重回调 → better-auth：基于插件 * Auth.js：会话处理有所不同 → better-auth：一致 **迁移步骤**： 1. **数据库架构**：Auth.js 和 better-auth 使用类似的架构，但列名不同 -- 将 Auth.js 映射到 better-auth ALTER TABLE 用户将列 emailVerified 重命名为 email_verified； ——等等 2. **更换配置** : // 之前 (Auth.js) 从 'next-auth' 导入 NextAuth 从“next-auth/providers/google”导入 GoogleProvider 导出默认 NextAuth({ 提供商：[GoogleProvider({ /* ... */ })] }) // 之后（更好的验证）从 'better-auth' 导入 { betterAuth } 导出 const auth = betterAuth({ 社交提供者：{ 谷歌：{ /* ... */ } } }) 3. **更新客户端挂钩**： // 之前从 'next-auth/react' 导入 { useSession } // 之后从 'better-auth/client' 导入 { useSession } ** ** ## 已知问题和解决方案 ### 问题 1：D1 最终一致性 **问题**：写入后立即进行会话读取可能会返回 D1 中的陈旧数据。 **症状**：用户登录，但“getSession()”在下一个请求时返回 null。 **解决方案**：使用Cloudflare KV进行会话存储（强一致性）：从 'better-auth' 导入 { betterAuth } 导出 const auth = betterAuth({ database: d1Adapter(env.DB), // 用户、帐户会话：{ 存储：{ 获取：异步（会话ID）=> { const 会话 = 等待 env.SESSIONS_KV.get(sessionId) 返回会话？ JSON.parse(会话)：空 }, 设置：异步（sessionId，会话，ttl）=> { 等待 env.SESSIONS_KV.put( 会话 ID, JSON.stringify(会话), { 过期时间：ttl } ） }, 删除： async (sessionId) => { 等待 env.SESSIONS_KV.delete(sessionId) } } } }) **来源**： ** ** ### 问题 2：SPA 应用程序的 CORS **问题**：当身份验证 API 与前端的来源不同时，出现 CORS 错误。 **症状**：浏览器控制台中出现“Access-Control-Allow-Origin”错误。 **解决方案** : 在 Worker 中配置 CORS 标头：从 'hono' 导入 { Hono } 从 'hono/cors' 导入 { cors } const app = new Hono<{ 绑定: Env }>() app.use('/api/auth/*', cors({ 来源：['https://yourdomain.com'，'http://localhost:3000']，凭证：true，//允许cookie 允许方法：['GET'、'POST'、'PUT'、'DELETE'、'OPTIONS'] }）） app.all('/api/auth/*', 异步 (c) => { const auth = betterAuth({ /* ... */ }) 返回 auth.handler(c.req.raw) }) **来源**： ** ** ### 问题 3：Workers 中的会话序列化 **问题**：无法在 Cloudflare Workers 中序列化复杂的会话对象。 **症状**：`DataCloneError` 或会话数据丢失。 **解决方案**：保持会话数据最小化并可 JSON 序列化：导出 const auth = betterAuth({ 数据库：d1Adapter(env.DB), 会话：{ // 只包含可序列化的字段字段：{ 用户 ID：真实，电子邮件：真实，角色：真实 // 不包括：函数、日期、复杂对象 } } }) ** ** ### 问题 4：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 = `${process.env.NEXT_PUBLIC_API_URL}/api/auth/callback/google` console.log('在 Google Console 中配置此 URL:',callbackURL) ** ** ### 问题 5：电子邮件验证未发送 **问题**：电子邮件验证链接永远不会到达。 **症状**：用户注册，但没有收到电子邮件。 **解决方案**：实现 `sendVerificationEmail` 处理程序：导出 const auth = betterAuth({ 数据库：/* ... */, 电子邮件和密码：{ 启用：真，需要电子邮件验证：true， sendVerificationEmail: async ({ 用户, url, 令牌 }) => { // 使用您的电子邮件服务（SendGrid、重新发送等）等待发送电子邮件({ 至：用户.电子邮件，主题：“验证您的电子邮件”， html:`

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

验证电子邮件

或者使用此代码：${token}

` }) } } }) **对于 Cloudflare** ：使用 Cloudflare 电子邮件路由或外部服务（重新发送、SendGrid）。 ** ** ### 问题 6：JWT 令牌过期 **问题**：会话过期太快或永远不会过期。 **症状**：用户意外注销或注销后会话仍然存在。 **解决方案**：配置会话过期：导出 const auth = betterAuth({ 数据库：/* ... */, 会话：{ expiresIn: 60 * 60 * 24 * 7, // 7 天（以秒为单位） updateAge: 60 * 60 * 24 // 每24小时更新一次会话 } }) ** ** ### 问题 7：密码哈希性能 **问题**：Cloudflare Workers 上的注册/登录速度缓慢。 **症状**：身份验证请求需要 >1 秒。 **解决方案**：better-auth默认使用bcrypt，这是CPU密集型的。对于 Workers，确保正确的异步处理： // better-auth 在内部处理这个问题，但如果是自定义的：从 'bcryptjs' 导入 bcrypt // 使用异步版本（不同步） const hash = wait bcrypt.hash(password, 10) // ✅ const isValid = wait bcrypt.compare(password, hash) // ✅ // 不要使用： const hash = bcrypt.hashSync(password, 10) // ❌（块） **替代**：使用 better-auth 的内置哈希（已优化）。 ** ** ### 问题 8：社会提供者范围问题 **问题**：社交登录成功，但缺少用户数据（姓名、头像）。 **症状**：登录 Google/GitHub 后，`session.user.name` 为空。 **解决方案**：请求附加范围：社交提供者：{ 谷歌：{ clientId：process.env.GOOGLE_CLIENT_ID！， clientSecret：process.env.GOOGLE_CLIENT_SECRET！， range: ['openid', 'email', 'profile'] // 包含 'profile' 作为名称/图像 }, github: { clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, range: ['user:email', 'read:user'] // 'read:user' 获取完整个人资料 } } ** ** ### 问题 9：多租户数据泄露 **问题**：用户看到其他租户的数据。 **症状**：组织 A 中的用户看到组织 B 的数据。 **解决方案**：始终按租户 ID 过滤查询：从 'better-auth/plugins' 导入 { multiTenant } 导出 const auth = betterAuth({ 数据库：/* ... */, 插件：[ 多租户({ tenantIdHeader: 'x-租户-id', isolateData: true // 强制租户隔离 }) ] }) // 在 API 路由中 app.get('/api/data', 异步 (c) => { const 会话 = 等待 auth.getSession(c.req.raw) const tenantId = c.req.header('x-tenant-id') // 始终按租户过滤 const 数据 = 等待 db.query.items.findMany({ 其中：eq(items.tenantId,tenantId) }) 返回c.json(数据) }) ** ** ### 问题 10：误报率限制 **问题**：合法用户因速率限制而被阻止。 **症状**：正常使用时出现“请求过多”错误。 **解决方案**：使用IP+用户ID作为限速键：从'better-auth/plugins'导入{rateLimit} 插件：[ 速率限制({ 窗户：60，最大：10，密钥生成器：（请求）=> { // 组合 IP 和用户 ID（如果经过身份验证） const ip = req.headers.get('cf-connecting-ip') || “未知” const userId = req.session?.userId || “匿名” 返回 `${ip}:${userId}` } }) ] ** ** ## 比较：更好的验证与替代方案特色 |更好的认证 |文员| Auth.js ---|---|---|--- **托管** |自托管 |第三方|自托管 **成本** |免费（OSS）| $25/月+ |免费（开源软件） **Cloudflare D1** | ✅ 头等舱 | ❌ 否 | ✅ 适配器 **社交认证** | ✅ 10+ 提供商 | ✅ 很多 | ✅ 很多 **2FA/密钥** | ✅ 插件 | ✅ 内置 | ⚠️有限 **组织** | ✅ 插件 | ✅ 内置 | ❌ 没有 **多租户** | ✅ 插件 | ✅ 是的 | ❌ 没有 **RBAC** | ✅ 插件 | ✅ 是的 | ⚠️定制 **魔法链接** | ✅ 内置 | ✅ 是的 | ✅ 是的 **电子邮件/密码** | ✅ 内置 | ✅ 是的 | ✅ 是的 **会话管理** | ✅ JWT + 数据库 | ✅ 智威汤逊 | ✅ 智威汤逊+数据库 **打字稿** | ✅ 头等舱 | ✅ 是的 | ✅ 是的 **框架支持** | ✅ 不可知论 | ⚠️ 以 React 为中心 | ✅ 不可知论者 **供应商锁定** | ✅ 无 | ❌ 高 | ✅ 无 **定制** | ✅ 完全掌控 | ⚠️ 有限公司 | ✅ 完全控制 **生产就绪** | ✅ 是的 | ✅ 是的 | ✅ 是的 **建议**： * **如果**使用更好的身份验证：自托管，Cloudflare D1，想要完全控制，避免供应商锁定 * **使用 Clerk 如果**：想要托管服务，不介意成本，需要最快的设置 * **使用Auth.js if** : 已经使用Next.js，基本需求，熟悉一下 ** ** ## 最佳实践 ### 安全 1. **在生产中始终使用 HTTPS**（无一例外） 2. **定期轮换机密**： # 生成新的秘密 openssl 兰德-base64 32 # 牧马人更新牧马人秘密放入 BETTER_AUTH_SECRET 3. **验证电子邮件域**以进行注册：电子邮件和密码：{ 启用：真，验证：异步（电子邮件）=> { const blockDomains = ['tempmail.com', 'guerrillamail.com'] const 域 = email.split('@')[1] if (blockedDomains.includes(domain)) { 抛出新错误（'电子邮件域不允许'） } } } 4. **启用CSRF保护**（better-auth中默认启用） 5. **对身份验证端点使用速率限制** 6. **记录身份验证事件**以进行安全监控： onSuccess：异步（用户，操作）=> { 等待 logAuthEvent({ 用户ID：用户ID， action, // '登录', '注册', '密码更改' 时间戳：新日期（）， ipAddress: req.headers.get('cf-connecting-ip') }) } ** ** ### 性能 1. **缓存会话查找**（对Workers使用KV）： const 会话 = 等待 env.SESSIONS_KV.get(sessionId) if (会话) 返回 JSON.parse(会话) // 如果不在缓存中则回退到数据库 const dbSession = 等待 db.query.sessions.findFirst(/* ... */) 等待 env.SESSIONS_KV.put(sessionId, JSON.stringify(dbSession)) 2. **对经常查询的字段使用索引**：在会话上创建索引 idx_sessions_user_id(userId); 在帐户上创建索引 idx_accounts_provider（provider，providerAccountId）； 3. **最小化会话数据**（仅重要字段） 4. **使用 CDN** 作为身份验证端点（缓存公共路由）： // 缓存 GET /api/auth/session 5 分钟 c.header('Cache-Control', 'public, max-age=300') ** ** ### 开发工作流程 1. **使用特定于环境的配置**： const isDev = process.env.NODE_ENV === '开发' 导出 const auth = betterAuth({ 数据库：/* ... */, 基本URL： isDev ？ 'http://localhost:3000' : 'https://yourdomain.com', 会话：{ 过期时间：isDev ？ 60 * 60 * 24 * 365 // 开发时间 1 年 : 60 * 60 * 24 * 7 // 7 天的产品 } }) 2. **使用 ngrok 在本地测试社交身份验证：恩格洛克 http 3000 # 在 OAuth 提供程序中使用 ngrok URL 作为重定向 URI 3. **种子测试用户**用于开发： // 种子.ts const testUsers = [ { 电子邮件：'admin@test.com'，密码：'password123'，角色：'admin' }, { 电子邮件：'user@test.com'，密码：'password123'，角色：'user' } ] for (testUsers 的常量用户) { 等待 authClient.signUp.email(用户) } ** ** ## 捆绑资源该技能包括以下参考实现： 1. **`scripts/setup-d1.sh`** \- Cloudflare Workers 的自动化 D1 数据库设置 2. **`references/cloudflare-worker-example.ts`** \- 具有身份验证 + 受保护路由的完整 Worker 3. **`references/nextjs-api-route.ts`** \- Next.js API 路由模式 4. **`references/react-client-hooks.tsx`** \- 带有 auth hooks 的 React 组件 5. **`references/drizzle-schema.ts`** \- 用于更好验证表的 Drizzle ORM 模式 6. **`assets/auth-flow-diagram.md`** \-OAuth、电子邮件验证的可视化流程图需要时使用“读取”工具访问这些文件。 ** ** ## 代币效率 **没有此技能**：约 15,000 个令牌（设置试错、调试 CORS、D1 适配器、OAuth 流程） **使用此技能**：约 4,500 个令牌（从模式直接实现） **节省**：约 70%（10,500 个令牌） **防止错误**：记录了 10 个常见问题并提供了解决方案 ** ** ## 其他资源 * **官方文档**： * **GitHub**： * **示例** : * **不和谐**： * **迁移指南**： ** ** ## 版本兼容性 **测试使用**： * `better-auth@1.3.34` * `@cloudflare/workers-types@latest` * `毛毛雨-orm@0.30.0` * `hono@4.0.0` * Node.js 18+，Bun 1.0+ **重大更改**：升级时检查更改日志： ** ** **最后验证**：2025-10-31 | **技能版本**：1.0.0

更好的身份验证

包含技能