在 NestJS + Next.js App Router…

为 TypeScript 全栈应用（NestJS 后端、Next.js App Router 前端、Drizzle ORM、PostgreSQL）配置 Better Auth 认证体系的适用场景。

适用场景

解决思路

1. 后端安装依赖：`npm install better-auth @auth/drizzle-adapter drizzle-orm pg`，并安装开发依赖 `npm install -D drizzle-kit`。
2. 前端安装依赖：`npm install better-auth`。
3. 按 4 阶段实施：1）数据库：安装 Drizzle、配置 schema、运行迁移；2）后端：用 NestJS module 创建 Better Auth 实例；3）前端：配置 auth client、创建页面、添加 middleware；4）插件：按需添加 2FA、passkey、organizations。
4. 数据库阶段安装依赖：`npm install drizzle-orm pg @auth/drizzle-adapter better-auth`，并安装开发依赖 `npm install -D drizzle-kit`。
5. 创建 `drizzle.config.ts`，使用 `defineConfig`，设置 `schema: './src/auth/schema.ts'`、`out: './drizzle'`、`dialect: 'postgresql'`、`dbCredentials: { url: process.env.DATABASE_URL! }`。
6. 按 `references/schema.md` 配置 Drizzle ORM schema。
7. 生成并运行迁移：`npx drizzle-kit generate`，`npx drizzle-kit migrate`。
8. 数据库检查点：运行 `psql $DATABASE_URL -c "\dt"`，确认出现 `user`、`account`、`session`、`verification_token` 表。
9. 后端阶段创建 database module，设置 Drizzle 连接服务。
10. 配置 Better Auth 实例：在 `src/auth/auth.instance.ts` 中从 `better-auth` 导入 `betterAuth`，从 `@auth/drizzle-adapter` 导入 `drizzleAdapter`，导入 `* as schema from './schema'`，调用 `betterAuth({ database: drizzleAdapter(schema, { provider: 'postgresql' }), emailAndPassword: { enabled: true }, socialProviders: { github: { clientId: process.env.AUTH_GITHUB_CLIENT_ID!, clientSecret: process.env.AUTH_GITHUB_CLIENT_SECRET! } } })`。
11. 创建 auth controller：在 `@Controller('auth')` 中定义 `@All('*') async handleAuth(@Req() req: Request, @Res() res: Response) { return auth.handler(req); }`。
12. 后端检查点：测试 `GET /auth/get-session`，未认证时应返回 `{ session: null }` 且无错误。
13. 前端阶段配置 auth client：在 `lib/auth.ts` 中从 `better-auth/client` 导入 `createAuthClient`，并 `export const authClient = createAuthClient({ baseURL: process.env.NEXT_PUBLIC_APP_URL! })`。
14. 添加 middleware：在 `middleware.ts` 中从 `@/lib/auth` 导入 `auth`，`export default auth((req) => { if (!req.auth && req.nextUrl.pathname.startsWith('/dashboard')) { return Response.redirect(new URL('/sign-in', req.nextUrl.origin)); } })`，并 `export const config = { matcher: ['/dashboard/:path*'] }`。
15. 创建 sign-in page，包含表单或社交按钮。
16. 前端检查点：未登录访问 `/dashboard` 时应重定向到 `/sign-in`。
17. 高级功能阶段按 `references/plugins.md` 添加插件：2FA 使用 `twoFactor({ issuer: 'AppName', otpOptions: { sendOTP } })`；Passkey 使用 `passkey({ rpID: 'domain.com', rpName: 'App' })`；Organizations 使用 `organization({ avatar: { enabled: true } })`；Magic Link 使用 `magicLink({ sendMagicLink })`；SSO 使用 `sso({ saml: { enabled: true } })`。
18. 添加插件后检查点：重新运行迁移，并验证新表存在。
19. 示例 1：在 Next.js Server Component 中显示会话：`app/dashboard/page.tsx` 使用从 `@/lib/auth` 导入的 `auth` 和 `redirect`，`const session = await auth()`，若 `!session` 则 `redirect('/sign-in')`，否则渲染 `session.user.name` 和 `session.user.email`。
20. 示例 2：2FA TOTP 与受信任设备：服务端配置 `twoFactor({ issuer: 'MyApp', otpOptions: { async sendOTP({ user, otp }, ctx) { await sendEmail({ to: user.email, subject: 'Your verification code', body: `Code: ${otp}` }); } } })`。
21. 示例 2：客户端调用 `authClient.twoFactor.verifyTotp({ code, trustDevice: true })`，成功后 `router.push('/dashboard')`；设备受信任 30 天。
22. 示例 3：Passkey 注册和登录：服务端从 `@better-auth/passkey` 导入 `passkey`，配置 `passkey({ rpID: 'example.com', rpName: 'My App' })`。
23. 示例 3：客户端注册 passkey：调用 `authClient.passkey.register({ name: 'My Device' })`。
24. 示例 3：客户端登录 passkey：调用 `authClient.signIn.passkey({ autoFill: true })`，让浏览器提示 passkey。
25. 更多示例（backup codes、organizations、magic link、conditional UI）参考 `references/plugins.md` 和 `references/passkey.md`。
26. 最佳实践：所有密钥放在 `.env`，并加入 `.gitignore`。
27. 最佳实践：使用 `openssl rand -base64 32` 生成 `BETTER_AUTH_SECRET`。
28. 最佳实践：OAuth 回调需要 HTTPS，本地测试用 `ngrok`。
29. 最佳实践：根据安全需求配置会话过期时间，默认 7 天。
30. 最佳实践：在 `email`、`userId` 上添加数据库索引以提升性能。
31. 最佳实践：错误处理返回通用错误，不暴露敏感细节。
32. 最佳实践：在认证端点添加限流，防止暴力破解。
33. 最佳实践：使用 `npx better-auth typegen` 获得完整 TypeScript 类型覆盖。
34. 安全：绝不提交密钥，将 `.env` 加入 `.gitignore`；永不提交 OAuth 密钥或数据库凭据。
35. 安全：始终验证 OAuth 重定向 URL，防止开放重定向。
36. 安全：让 Better Auth 自动处理密码哈希，绝不实现自定义哈希。
37. 安全：生产环境使用 Redis 或其他可扩展 session 存储。
38. 安全：生产环境认证始终使用 HTTPS。
39. 安全：对基于密码的认证始终实现邮箱验证。

适用边界 · 注意事项

• 不使用 NestJS、Next.js App Router、Drizzle ORM、PostgreSQL 这一技术栈时，不能直接照搬该集成模式。
• Node.js 低于 18，或 Passkey 场景无法使用 HTTPS/兼容浏览器时，不适合使用对应能力。
• 不愿新增认证相关数据库表（如 organization 功能需要额外表），或需要完全自定义认证协议而非引入 Better Auth 时，不适合使用。