创建身份验证技能

使用 Better Auth 为 TypeScript/JavaScript 应用程序添加身份验证的指南。

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

阶段 1：规划（实施前必需）

在编写任何代码之前，通过扫描项目并向用户提出结构化问题来收集需求。这可确保实现满足他们的需求。

步骤 1：扫描项目

分析代码库以自动检测：

• 框架 — 查找 next.config, svelte.config, nuxt.config, astro.config, vite.config，或 Express/Hono 入口文件。
• 数据库/对象关系映射 — 查找 prisma/schema.prisma, drizzle.config, package.json 依赖项（pg, mysql2, better-sqlite3, mongoose, mongodb）。
• 现有身份验证 — 在 package.json 或导入中查找现有的身份验证库（next-auth, lucia, clerk, supabase/auth, firebase/auth）。
• 包管理器 — 检查是否存在 pnpm-lock.yaml, yarn.lock, bun.lockb 或 package-lock.json。

使用你找到的信息来预填默认值，并跳过你已经可以回答的问题。

步骤 2：提出规划问题

使用 AskQuestion 工具在单次调用中向用户提出所有适用的问题。跳过任何你已从扫描中获得确切答案的问题。将它们归入标题下，例如”身份验证设置规划”。

要问的问题：

1. 项目类型（如果已检测到则跳过）
   • 提示：”这是什么类型的项目？”
   • 选项：从头开始的新项目 | 为现有项目添加身份验证 | 从其他身份验证库迁移
2. 框架（如果已检测到则跳过）
   • 提示：”你正在使用哪个框架？”
   • 选项：Next.js（应用程序路由器） | Next.js（页面路由器） | SvelteKit | Nuxt | Astro | Express | Hono | SolidStart | 其他
3. 数据库与对象关系映射（如果已检测到则跳过）
   • 提示：”你将使用哪种数据库设置？”
   • 选项：PostgreSQL（Prisma） | PostgreSQL（Drizzle） | PostgreSQL（pg 驱动） | MySQL（Prisma） | MySQL（Drizzle） | MySQL（mysql2 驱动） | SQLite（Prisma） | SQLite（Drizzle） | SQLite（better-sqlite3 驱动） | MongoDB（Mongoose） | MongoDB（原生驱动）
4. 身份验证方法（始终询问，允许多选）
   • 提示：”你需要哪些登录方式？”
   • 选项：邮箱与密码 | 社交 OAuth（谷歌、GitHub 等） | 魔法链接（无密码邮箱） | 通行密钥（WebAuthn） | 手机号码
   • allow_multiple： true
5. 社交提供商（仅当用户在上面选择了社交 OAuth 时询问——在后续调用中询问）
   • 提示：”你需要哪些社交提供商？”
   • 选项：谷歌 | GitHub | 苹果 | 微软 | Discord | 推特/X
   • allow_multiple： true
6. 邮箱验证（仅当上面选择了邮箱与密码时询问——在后续调用中询问）
   • 提示：”你是否需要邮箱验证？”
   • 选项：是 | 否
7. 邮箱提供商（仅当邮箱验证为是，或在功能中选择了密码重置时询问——在后续调用中询问）
   • 提示：”你想如何发送电子邮件？”
   • 选项：Resend | 暂时模拟（控制台输出）
8. 功能与插件（始终询问，允许多选）
   • 提示：”你需要哪些附加功能？”
   • 选项：双因素身份验证 (2FA) | 组织/团队 | 管理仪表板 | 应用程序编程接口令牌 | 密码重置 | 以上都不需要
   • allow_multiple： true
9. 身份验证页面（始终询问，允许多选——根据之前的回答预选）
   • 提示：”你需要哪些身份验证页面？”
   • 选项因之前的回答而异：
     • 始终可用：登录 | 注册
     • 如果选择了邮箱与密码：忘记密码 | 重置密码
     • 如果启用了邮箱验证：邮箱验证
   • allow_multiple： true
10. 身份验证用户界面样式（始终询问）

• 提示：”你想要什么风格的认证页面？选择一个或描述你自己的。”
• 选项：极简干净 | 居中卡片带背景 | 分割布局（表单 + 主图） | 悬浮 / 毛玻璃效果 | 其他（我来描述）

步骤 3：总结计划

收集答案后，以 Markdown 检查清单的形式呈现一个简洁的实施计划。示例：

## 身份验证实施计划

- **框架：** Next.js（应用程序路由器）
- **数据库：** 通过 Prisma 使用 PostgreSQL
- **身份验证方法：** 邮箱/密码、谷歌 OAuth、GitHub OAuth
- **插件：** 双因素身份验证、组织、邮箱验证
- **用户界面：** 自定义表单

### 步骤
1. 安装 `better-auth` 和 `@better-auth/cli`
2. 创建包含服务器配置的 `lib/auth.ts`
3. 创建包含 React 客户端的 `lib/auth-client.ts`
4. 在 `app/api/auth/[...all]/route.ts` 设置路由处理程序
5. 配置 Prisma 适配器并生成架构
6. 添加谷歌和 GitHub OAuth 提供商
7. 启用 `twoFactor` 和 `organization` 插件
8. 设置邮箱验证处理程序
9. 运行迁移
10. 创建登录 / 注册页面

在进入阶段 2 之前，要求用户确认该计划。

阶段 2：实施

只有在用户确认阶段 1 的计划后，才能继续执行此阶段。

遵循下面的决策树，由上面收集的答案引导。

这是新/空项目吗？
├─ 是 → 新项目设置
│   1. 安装 better-auth（+ 根据计划安装范围包）
│   2. 创建包含所有计划配置的 auth.ts
│   3. 创建包含框架客户端的 auth-client.ts
│   4. 设置路由处理程序
│   5. 设置环境变量
│   6. 运行命令行界面迁移/生成
│   7. 根据计划添加插件
│   8. 创建身份验证用户界面页面
│
├─ 迁移中 → 从现有身份验证迁移
│   1. 审计当前身份验证，找出差距
│   2. 计划增量迁移
│   3. 与现有身份验证并存安装 better-auth
│   4. 迁移路由，然后迁移会话逻辑，然后迁移用户界面
│   5. 移除旧的身份验证库
│   6. 参阅文档中的迁移指南
│
└─ 添加中 → 为现有项目添加身份验证
    1. 分析项目结构
    2. 安装 better-auth
    3. 创建匹配计划的身份验证配置
    4. 添加路由处理程序
    5. 运行架构迁移
    6. 集成到现有页面中
    7. 添加计划的插件和功能

在实施结束时，全面指导用户完成后续步骤（例如，设置 OAuth 应用程序凭据、部署环境变量、测试流程）。

安装

核心： npm install better-auth

范围包（根据需要）：

环境变量

BETTER_AUTH_SECRET=<32+ 字符，使用以下命令生成： openssl rand -base64 32>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=<你的数据库连接字符串>

根据需要添加 OAuth 密钥：GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GOOGLE_CLIENT_ID 等。

服务器配置 (auth.ts)

位置： lib/auth.ts 或 src/lib/auth.ts

最小配置需要：

• database – 连接或适配器
• emailAndPassword： { enabled： true } – 用于邮箱/密码认证

标准配置添加：

• socialProviders – OAuth 提供商（谷歌、GitHub 等）
• emailVerification.sendVerificationEmail – 邮箱验证处理程序
• emailAndPassword.sendResetPassword – 密码重置处理程序

完整配置添加：

• plugins – 功能插件数组
• session – 过期时间、cookie 缓存设置
• account.accountLinking – 多提供商账户关联
• rateLimit – 速率限制配置

导出类型： export type Session = typeof auth.$Infer.Session

客户端配置 (auth-client.ts)

按框架导入：

客户端插件放在 createAuthClient({ plugins： [...] }) 中。

常用导出： signIn, signUp, signOut, useSession, getSession

路由处理程序设置

Next.js 服务器组件： 将 nextCookies() 插件添加到身份验证配置中。

数据库迁移

添加插件后重新运行。

数据库适配器

常用插件

插件模式： 服务器插件 + 客户端插件 + 运行迁移。

身份验证用户界面实现

登录流程：

1. signIn.email({ email, password }) 或 signIn.social({ provider, callbackURL })
2. 处理响应中的 error
3. 成功后重定向

会话检查（客户端）： useSession() 钩子返回 { data： session, isPending }

会话检查（服务器）： auth.api.getSession({ headers： await headers() })

受保护的路由： 检查会话，如果为空则重定向到 /sign-in。

安全检查清单

• BETTER_AUTH_SECRET 已设置（32+ 字符）
• 生产环境中 advanced.useSecureCookies： true
• trustedOrigins 已配置
• 已启用速率限制
• 已启用邮箱验证
• 已实现密码重置
• 敏感应用启用双因素身份验证
• 未禁用 CSRF 保护
• 已审查 account.accountLinking 配置

故障排除

资源

• 文档
• 示例
• 插件
• 命令行界面
• 迁移指南