# 更好的认证技巧 Better Auth 是一个全面的、与框架无关的 TypeScript 身份验证和授权框架，提供对电子邮件/密码身份验证、社交登录的内置支持，以及用于高级功能的强大插件生态系统。 ## 何时使用此技能在以下情况下使用此技能： * 在 TypeScript/JavaScript 应用程序中实现身份验证 * 添加电子邮件/密码或社交 OAuth 身份验证 * 设置 2FA、密钥、魔术链接或其他高级身份验证功能 * 在组织支持下构建多租户应用程序 * 实现会话管理和用户管理 * 使用任何框架（Next.js、Nuxt、SvelteKit、Remix、Astro、Hono、Express 等） ## 核心概念 ### 主要特点 * **与框架无关**：适用于任何框架（Next.js、Nuxt、Svelte、Remix、Hono、Express 等） * **内置身份验证方法**：电子邮件/密码和 OAuth 2.0 社交提供商 * **插件生态系统**：易于添加高级功能（2FA、密钥、魔术链接、用户名、电子邮件 OTP、组织等） * **数据库灵活性**：支持 SQLite、PostgreSQL、MySQL、MongoDB 等 * **ORM 支持**：适用于 Drizzle、Prisma、Kysely 和 MongoDB 的内置适配器 * **类型安全**：完整的 TypeScript 支持和出色的类型推断 * **会话管理**：客户端和服务器的内置会话处理 ### 架构 Better Auth 遵循客户端-服务器架构： 1. **服务器实例**（`better-auth`）：处理身份验证逻辑、数据库操作和 API 路由 2. **客户端实例** (`better-auth/client`)：提供用于身份验证的钩子和方法 3. **插件**：扩展服务器和客户端功能 ## 安装和设置 ### 第 1 步：安装包 npm 安装更好的身份验证 # 或 pnpm 添加更好的身份验证 # 或纱线添加更好的认证 # 或面包添加更好的身份验证 ### 步骤 2：环境变量创建 `.env` 文件： BETTER_AUTH_SECRET=<生成的秘密密钥> BETTER_AUTH_URL=http://localhost:3000 生成密钥：使用 openssl 或随机字符串生成器（至少 32 个字符）。 ### 步骤 3：创建身份验证服务器实例在项目根目录、“lib/”、“utils/”中创建“auth.ts”，或嵌套在“src/”、“app/”或“server/”下：从“better-auth”导入{betterAuth}；导出 const auth = betterAuth({ 数据库：{ // 数据库配置 }, 电子邮件和密码：{ 启用：真， autoSignIn: true // 用户注册后自动登录 }, 社交提供者：{ github: { clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, }, 谷歌：{ clientId：process.env.GOOGLE_CLIENT_ID！， clientSecret：process.env.GOOGLE_CLIENT_SECRET！， } } }); ### 步骤 4：数据库配置选择您的数据库设置： **直接数据库连接：** 从“better-auth”导入{betterAuth}；从“better-sqlite3”导入数据库； // 或从 "pg" 导入 { Pool }; // 或 import { createPool } from "mysql2/promise"; 导出 const auth = betterAuth({ 数据库：新数据库（“./sqlite.db”）， // 或: new Pool({ connectionString: process.env.DATABASE_URL }) // 或: createPool({ 主机: "localhost", 用户: "root", ... }) }); **ORM 适配器：** // 毛毛雨从“better-auth/adapters/drizzle”导入{ drizzleAdapter }；从“@/db”导入{db}；导出 const auth = betterAuth({ 数据库：drizzleAdapter(db, { 提供商：“pg”，//或“mysql”，“sqlite” }), }); // 棱镜从“better-auth/adapters/prisma”导入 { prismaAdapter }；从“@prisma/client”导入 { PrismaClient }； const prisma = new PrismaClient(); 导出 const auth = betterAuth({ 数据库：prismaAdapter(prisma, { 提供者：“postgresql”， }), }); // MongoDB 从“better-auth/adapters/mongodb”导入{ mongodbAdapter }；从“@/db”导入{客户端}；导出 const auth = betterAuth({ 数据库：mongodbAdapter（客户端）， }); ### 步骤 5：创建数据库架构使用更好的身份验证 CLI： # 生成架构/迁移文件 npx @better-auth/cli 生成 # 或者直接迁移（仅限 Kysely 适配器） npx @better-auth/cli 迁移 ### 第 6 步：挂载 API 处理程序为 `/api/auth/*` 创建包罗万象的路由： **Next.js（应用程序路由器）：** // 应用程序/api/auth/[...all]/route.ts 从“@/lib/auth”导入{auth}；从“better-auth/next-js”导入{ toNextJsHandler }；导出 const { POST, GET } = toNextJsHandler(auth); **努克斯：** // 服务器/api/auth/[...all].ts 从“~/utils/auth”导入{auth}；导出默认的defineEventHandler((事件) => { 返回 auth.handler(toWebRequest(event)); }); **SvelteKit：** // 钩子.server.ts 从“$lib/auth”导入{auth}；从“better-auth/svelte-kit”导入{ svelteKitHandler }；导出异步函数句柄（{事件，解析}）{ 返回 svelteKitHandler({ 事件, 解析, 身份验证 }); } **荣誉：** 从“hono”导入{Hono}；从“./auth”导入{auth}； const app = new Hono(); app.on(["POST", "GET"], "/api/auth/*", (c) => auth.handler(c.req.raw)); **快递：** 从“快递”进口快递；从“better-auth/node”导入 { toNodeHandler }；从“./auth”导入{auth}；常量应用程序 = Express(); app.all("/api/auth/*", toNodeHandler(auth)); ### 第 7 步：创建客户端实例创建`auth-client.ts`：从“better-auth/client”导入{createAuthClient}；导出 const authClient = createAuthClient({ 基本URL：process.env.NEXT_PUBLIC_BETTER_AUTH_URL || “http://localhost:3000” }); ## 验证方法 ### 电子邮件和密码 **服务器配置：** 导出 const auth = betterAuth({ 电子邮件和密码：{ 启用：真， autoSignIn: true, // 默认值：true } }); **客户端使用情况：** // 注册 const { 数据，错误 } = 等待 authClient.signUp.email({ 电子邮件：“user@example.com”，密码：“securePassword123”，姓名：“约翰·多伊”， image: "https://example.com/avatar.jpg", // 可选 callbackURL: "/dashboard" // 可选 }, { onSuccess: (ctx) => { // 重定向或显示成功 }, 错误：(ctx) => { 警报（ctx.错误.消息）； } }); // 登录 const { 数据，错误 } = 等待 authClient.signIn.email({ 电子邮件：“user@example.com”，密码：“securePassword123”，回调URL：“/仪表板”， RememberMe: true // 默认值：true }); ### 社交 OAuth **服务器配置：** 导出 const auth = betterAuth({ 社交提供者：{ github: { clientId: process.env.GITHUB_CLIENT_ID!, clientSecret: process.env.GITHUB_CLIENT_SECRET!, }, 谷歌：{ clientId：process.env.GOOGLE_CLIENT_ID！， clientSecret：process.env.GOOGLE_CLIENT_SECRET！， }, // 其他提供商：apple、discord、facebook 等。 } }); **客户端使用情况：** 等待 authClient.signIn.social({ 提供者：“github”，回调URL：“/仪表板”，错误回调URL：“/错误”， newUserCallbackURL: "/welcome", }); ### 退出等待 authClient.signOut({ 获取选项：{ 成功：() => { 路由器.push(“/登录”); } } }); ## 会话管理 ### 客户端会话 **使用 Hooks（React/Vue/Svelte/Solid）：** // 反应从“@/lib/auth-client”导入{authClient}；导出函数 UserProfile() { const { 数据：会话，isPending，错误 } = authClient.useSession(); if (isPending) return

正在加载...

; if (error) return

错误: {error.message}

; return

欢迎，{session?.user.name}!

; } // 视图 <脚本设置> 从“~/lib/auth-client”导入{authClient}； const 会话 = authClient.useSession(); <模板>

// 苗条 <脚本> 从“$lib/auth-client”导入{authClient}； const 会话 = authClient.useSession();

{$session.data?.user.email}

**使用 getSession：** const { 数据：会话，错误 } = 等待 authClient.getSession(); ### 服务器端会话 // Next.js 从“./auth”导入{auth}；从“next/headers”导入{ headers }； const 会话 = 等待 auth.api.getSession({ 标题：等待标题（） }); // 霍诺 app.get("/protected", 异步 (c) => { const 会话 = 等待 auth.api.getSession({ 标头：c.req.raw.headers }); 如果（！会话）{ return c.json({ 错误: "未经授权" }, 401); } return c.json({ user: session.user }); }); ## 插件系统 Better Auth 的插件系统允许轻松添加高级功能。 ### 使用插件 **服务器端：** 从“better-auth”导入{betterAuth}；从“better-auth/plugins”导入{twoFactor，组织，用户名}；导出 const auth = betterAuth({ 插件：[ 双因子(), 组织（），用户名(), ] }); **客户端：** 从“better-auth/client”导入{createAuthClient}；导入{ 双因素客户端，组织客户，用户名客户来自“better-auth/client/plugins”；导出 const authClient = createAuthClient({ 插件：[ 两个因素客户端（{ 二因素页：“/二因素” }), 组织客户端(), 用户名客户端() ] }); **添加插件后：** # 重新生成架构 npx @better-auth/cli 生成 # 应用迁移 npx @better-auth/cli 迁移 ### 流行插件 #### 双因素身份验证 (2FA) // 服务器从“better-auth/plugins”导入{twoFactor}；导出 const auth = betterAuth({ 插件：[twoFactor()] }); // 客户端从“better-auth/client/plugins”导入{twoFactorClient}；导出 const authClient = createAuthClient({ 插件：[ TwoFactorClient({ TwoFactorPage: "/two-factor" }) ] }); // 用法等待 authClient.twoFactor.enable({ 密码: "userPassword" }); 等待 authClient.twoFactor.verifyTOTP({ 代码：“123456”，信任设备：true }); #### 用户名认证 // 服务器从“better-auth/plugins”导入{用户名}；导出 const auth = betterAuth({ 插件：[用户名()] }); // 客户端从“better-auth/client/plugins”导入{ usernameClient }； // 使用用户名注册等待 authClient.signUp.username({ 用户名：“johndoe”，密码：“securePassword123”，姓名：“约翰·多伊” }); #### 魔法链接从“better-auth/plugins”导入{ magicLink }；导出 const auth = betterAuth({ 插件：[ 魔法链接({ sendMagicLink: async ({ email, url }) => { // 发送带有魔术链接的电子邮件等待发送电子邮件（电子邮件，网址）； } }) ] }); #### 密钥 (WebAuthn) 从“better-auth/plugins”导入{passkey}；导出 const auth = betterAuth({ 插件：[密码()] }); // 客户端等待 authClient.passkey.register(); 等待 authClient.passkey.signIn(); #### 组织/多租户从“better-auth/plugins”导入{组织}；导出 const auth = betterAuth({ 插件：[组织()] }); // 客户端等待 authClient.organization.create({ 名称：“Acme Corp”， slug：“极限” }); 等待 authClient.organization.inviteMember({ 组织 ID：“组织 ID”，电子邮件：“user@example.com”，角色：“成员” }); ## 高级配置 ### 电子邮件验证导出 const auth = betterAuth({ 电子邮件验证：{ sendVerificationEmail: async ({ 用户, url }) => { 等待 sendEmail(user.email, url); }, 发送注册：true } }); ### 速率限制导出 const auth = betterAuth({ 速率限制：{ 启用：真，窗口: 60, // 秒最大：10 // 请求 } }); ### 自定义会话过期导出 const auth = betterAuth({ 会话：{ expiresIn: 60 * 60 * 24 * 7, // 7 天（以秒为单位） updateAge: 60 * 60 * 24 // 每24小时更新一次 } }); ### CORS 配置导出 const auth = betterAuth({ 高级：{ cors选项：{ 来源：[“https://example.com”]，凭证：真实 } } }); ## 数据库架构 ### 核心表更好的身份验证需要这些核心表： * `user`: 用户帐户 * `session`: 活动会话 * `account`：OAuth 提供商连接 * `verification`: 电子邮件验证令牌 **使用 CLI 自动生成：** npx @better-auth/cli 生成 **文档中提供了手动模式：**检查 `/docs/concepts/database#core-schema` ## 最佳实践 1. **环境变量**：始终使用环境变量作为机密 2. **生产中的 HTTPS** ：将 `BETTER_AUTH_URL` 设置为 HTTPS URL 3. **会话安全**：在生产中使用安全cookie 4. **错误处理**：在客户端和服务器上实施正确的错误处理 5. **类型安全**：利用 TypeScript 类型实现更好的 DX 6. **插件顺序**：某些插件依赖于其他插件，请检查文档 7. **数据库迁移**：添加插件后始终运行迁移 8. **速率限制**：启用生产速率限制 9. **电子邮件验证**：实施电子邮件验证以确保安全 10. **密码要求**：根据需要自定义密码验证 ## 常见模式 ### 受保护的路由（服务器端） // Next.js 中间件从“@/lib/auth”导入{auth}；从“next/server”导入{ NextRequest, NextResponse }；导出异步函数中间件（请求：NextRequest）{ const 会话 = 等待 auth.api.getSession({ 标头：request.headers }); 如果（！会话）{ return NextResponse.redirect(new URL("/login", request.url)); } 返回 NextResponse.next(); } 导出常量配置= { 匹配器：[“/仪表板/：路径*”] }; ### 用户个人资料更新等待 authClient.updateUser({ 名称：“新名称”，图片：“https://example.com/new-avatar.jpg” }); ### 密码管理 // 修改密码等待 authClient.changePassword({ 当前密码：“旧密码”，新密码：“新密码” }); // 重置密码（忘记密码）等待 authClient.forgetPassword({ 电子邮件：“user@example.com”，重定向至：“/重置密码” }); 等待 authClient.resetPassword({ 令牌：“重置令牌”，密码：“新密码” }); ## 故障排除 ### 常见问题 1. **“无法找到身份验证实例”** * 确保 `auth.ts` 位于正确的位置（root、lib/、utils/） * 将 auth 实例导出为 `auth` 或默认导出 2. **数据库连接错误** * 验证数据库凭据 * 检查数据库服务器是否正在运行 * 确保您的数据库有正确的适配器 3. **CORS错误** * 在高级设置中配置`corsOptions` * 确保客户端和服务器 URL 匹配 4. **插件无法运行** * 添加插件后运行迁移 * 检查插件是否已添加到服务器和客户端 * 验证插件配置 ## 特定于框架的指南 * **Next.js** ：使用 Next.js 插件进行服务器操作 * **Nuxt** : 配置服务器中间件 * **SvelteKit** ：使用 hooks.server.ts * **Astro** ：正确设置API路由 * **Hono/Express** ：使用适当的节点处理程序 ## 资源 * 文档： * GitHub： * 插件： * 示例： ## 实施清单实施更好的身份验证时： * 安装`better-auth`包 * 设置环境变量（秘密、URL） * 创建认证服务器实例 * 配置数据库/适配器 * 运行架构迁移 * 配置认证方式 * 挂载 API 处理程序 * 创建客户端实例 * 实现注册/登录 UI * 添加会话管理 * 设置保护路由 * 根据需要添加插件 * 测试认证流程 * 配置电子邮件发送（如果需要） * 设置错误处理 * 启用生产速率限制

更好的身份验证

包含技能