Create Auth Skill

Create Auth Skill

使用 Better Auth 为 TypeScript/JavaScript 应用添加鉴权的指南。

代码示例与语法参见 better-auth.com/docs。

决策树

是否为新项目/空项目？
├─ 是 → 新项目搭建
│ 1. 确定框架
│ 2. 选择数据库
│ 3. 安装 better-auth
│ 4. 创建 auth.ts + auth-client.ts
│ 5. 配置路由处理器
│ 6. 运行 CLI migrate/generate
│ 7. 通过插件添加能力
│
└─ 否 → 项目是否已有鉴权？
 ├─ 是 → 迁移/增强
 │ • 审计现有鉴权缺口
 │ • 规划渐进式迁移
 │ • 参考文档中的迁移指南
 │
 └─ 否 → 为现有项目添加鉴权
 1. 分析项目结构
 2. 安装 better-auth
 3. 创建 auth 配置
 4. 添加路由处理器
 5. 运行 schema 迁移
 6. 接入现有页面

安装

核心： 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 提供方（google、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 Server Components： 在 auth 配置中添加 nextCookies() 插件。

数据库迁移

添加插件后需重新执行。

数据库适配器

常用插件

插件用法： 服务端插件 + 客户端插件 + 执行迁移。

鉴权 UI 实现

登录流程：

1. signIn.email({ email, password }) 或 signIn.social({ provider, callbackURL })
2. 处理返回的 error
3. 成功时重定向

客户端会话检查： useSession() 返回 { data: session, isPending }

服务端会话检查： auth.api.getSession({ headers: await headers() })

受保护路由： 检查 session，为空则重定向到 /sign-in。

安全清单

• 设置 BETTER_AUTH_SECRET（32+ 字符）
• 生产环境启用 advanced.useSecureCookies: true
• 配置 trustedOrigins
• 启用限流
• 启用邮箱验证
• 实现密码重置
• 敏感应用启用 2FA
• 不要关闭 CSRF 防护
• 审查 account.accountLinking

故障排查

参考

• 文档
• 示例
• 插件
• CLI
• 迁移指南