名称: next-js-better-auth-集成 类别: 身份验证 作者: Claude 版本: 1.0.0 标签: [nextjs, better-auth, 身份验证, app-router, 会话] 描述: 一个用于将 Better Auth 与 Next.js App Router 集成的概念性技能
Next.js Better Auth 集成技能
何时使用此技能
当您需要在 Next.js 应用程序中使用 App Router 架构和 Better Auth 实现身份验证时，请使用此概念性技能。此技能适用于：
- 向 Next.js 应用程序添加用户身份验证
- 使用 Better Auth 实现安全的会话管理
- 启用基于 JWT 的身份验证流程
- 在 Next.js 中创建受保护的路由和页面
- 跨应用程序管理用户会话
- 实现社交登录功能
此技能不应用于：
- 使用 Pages Router 的应用程序（改用 _app.js）
- 不需要用户身份验证的应用程序
- 没有用户交互的简单静态站点
- 具有与 Better Auth 冲突的自定义身份验证要求的应用程序
先决条件
- 启用 App Router 的 Next.js 13+
- 已安装并配置 Better Auth 包
- 了解 Next.js 中间件和服务器组件
- 了解身份验证概念和会话管理
- 用于安全管理身份验证密钥的环境
概念性实现框架
Better Auth 初始化能力
- 使用适当的提供程序和设置配置 Better Auth
- 设置身份验证数据库或适配器配置
- 定义用户模型和身份验证选项
- 初始化前端使用的身份验证客户端
- 配置身份验证回调和自定义
JWT 令牌启用能力
- 配置 JWT 令牌生成和验证设置
- 设置令牌过期和刷新机制
- 定义令牌有效负载结构和声明
- 启用安全的令牌存储和传输
- 配置令牌签名和验证算法
用于会话管理的应用程序包装能力
- 使用 Better Auth 提供程序包装 Next.js 应用程序
- 为客户端组件配置会话上下文
- 在服务器组件中设置服务器端会话访问
- 跨应用程序路由建立会话持久性
- 启用客户端和服务器之间的会话同步
钩子使用能力
- 通过钩子提供对身份验证状态的访问
- 在组件中启用用户会话数据检索
- 支持实时检查身份验证状态
- 允许自定义身份验证流程和回调
- 启用注销和会话管理功能
受保护路由实现能力
- 创建用于保护应用程序路由的中间件
- 实现服务器端身份验证检查
- 启用客户端会话验证
- 适当处理未经授权的访问场景
- 根据身份验证状态重定向用户
预期输入/输出
输入要求：
-
Better Auth 配置：
- 数据库连接设置
- 身份验证提供程序配置
- JWT 设置和密钥
- UI 和行为的自定义选项
- 回调 URL 和重定向设置
-
Next.js 应用程序结构：
- App Router 目录结构 (/app)
- 中间件配置 (middleware.ts)
- 需要身份验证上下文的布局文件
- 需要身份验证保护的页面
输出格式：
-
初始化的身份验证系统：
- 配置好的 Better Auth 实例
- 可立即使用的身份验证上下文
- 正确设置的会话管理
- 正常工作的 JWT 令牌系统
-
经过身份验证的组件状态：
- 组件中可用的用户会话数据
- 身份验证状态（已登录/已注销）
- 身份验证时的用户个人信息
- 会话令牌和刷新机制
-
受保护路由响应：
- 对已认证用户返回 HTTP 200 OK
- 对未认证用户返回 HTTP 302/307 重定向
- 对身份验证失败进行适当的错误处理
- 跨应用程序一致的会话状态
-
钩子结果：
- 用户身份验证状态
- 可用时的会话数据
- 身份验证检查期间的加载状态
- 身份验证失败的错误状态
集成模式
App Router 集成
- 配置根布局以提供身份验证上下文
- 实现用于路由保护的中间件
- 在服务器组件中使用服务器端会话访问
- 在客户端组件中利用交互式身份验证 UI
会话管理
- 服务器组件中的服务器端会话处理
- 客户端组件中的客户端会话同步
- 跨组件会话状态一致性
- 正确的会话清理和失效
身份验证流程
- 登录和注册流程管理
- 社交身份验证提供程序集成
- 密码重置和账户恢复
- 多因素身份验证（如果支持）
安全注意事项
- 令牌安全：安全的 JWT 令牌存储和传输
- 会话管理：正确的会话失效和刷新
- CSRF 防护：为表单实现 CSRF 防护
- 安全 Cookie：使用安全、仅 HTTP 的 Cookie 进行会话
- 输入验证：验证所有身份验证输入
- 速率限制：对身份验证端点实施速率限制
- 密钥管理：安全存储身份验证密钥
性能影响
- 优化中间件中的会话查找性能
- 考虑会话数据的缓存策略
- 尽量减少每个请求的身份验证开销
- 高效的令牌验证机制
- 尽可能延迟加载身份验证上下文
错误处理和验证
- 处理身份验证初始化失败
- 管理会话过期场景
- 为失败的身份验证提供适当的反馈
- 验证身份验证状态一致性
- 处理身份验证检查期间的网络故障
测试注意事项
- 在服务器组件中测试身份验证流程
- 验证跨请求的会话持久性
- 验证受保护路由的访问控制
- 测试 JWT 令牌生成和验证
- 验证社交登录提供程序集成
- 测试身份验证边缘情况和错误状态