name: Nuxt 更好认证模块 description: 使用@onmax/nuxt-better-auth在Nuxt应用中实现认证 - 提供useUserSession组合函数、服务器认证助手、路由保护和Better Auth插件集成。 license: MIT
Nuxt Better Auth
基于 Better Auth 构建的 Nuxt 4+ 认证模块。提供组合函数、服务器实用程序和路由保护。
Alpha 状态: 此模块目前处于 alpha 阶段（v0.0.2-alpha.19），不建议用于生产环境。API 可能更改。
使用场景
- 安装/配置
@onmax/nuxt-better-auth - 实现登录/注册/退出流程
- 保护路由（客户端和服务器端）
- 在 API 路由中访问用户会话
- 集成 Better Auth 插件（管理员、密码钥匙、双因素认证）
- 使用 NuxtHub 设置数据库
- 为外部认证后端使用 clientOnly 模式
- 添加
@nuxtjs/i18n的 i18n 支持
对于 Nuxt 模式: 使用 nuxt 技能
对于 NuxtHub 数据库: 使用 nuxthub 技能
可用指导
| 文件 | 主题 |
|---|---|
| references/installation.md | 模块设置、环境变量、配置文件 |
| references/client-auth.md | useUserSession、signIn/signUp/signOut、BetterAuthState、安全重定向 |
| references/server-auth.md | serverAuth、getUserSession、requireUserSession |
| references/route-protection.md | routeRules、definePageMeta、中间件 |
| references/plugins.md | Better Auth 插件（管理员、密码钥匙、双因素认证） |
| references/database.md | NuxtHub 集成、Drizzle 模式、带外键的自定义表 |
| references/client-only.md | 外部认证后端、clientOnly 模式、CORS |
| references/types.md | AuthUser、AuthSession、类型增强 |
加载文件
根据您的任务考虑加载这些参考文件：
- [ ] references/installation.md - 如果安装或配置模块
- [ ] references/client-auth.md - 如果构建登录/注册/退出流程
- [ ] references/server-auth.md - 如果保护 API 路由或在服务器端访问用户会话
- [ ] references/route-protection.md - 如果使用 routeRules 或 definePageMeta 进行认证
- [ ] references/plugins.md - 如果集成 Better Auth 插件（管理员、密码钥匙、双因素认证）
- [ ] references/database.md - 如果使用 NuxtHub 或 Drizzle 设置数据库
- [ ] references/client-only.md - 如果使用外部认证后端并启用 clientOnly 模式
- [ ] references/types.md - 如果处理 AuthUser、AuthSession 或类型增强
不要一次性加载所有文件。 仅加载与当前任务相关的内容。
关键概念
| 概念 | 描述 |
|---|---|
useUserSession() |
客户端组合函数 - 用户、会话、登录状态、登录/退出方法 |
requireUserSession() |
服务器助手 - 如果未认证则抛出 401/403 错误 |
auth 路由模式 |
'user'、'guest'、{ user: {...} } 或 false |
serverAuth() |
在服务器路由中获取 Better Auth 实例 |
快速参考
// 客户端：useUserSession()
const { user, loggedIn, signIn, signOut } = useUserSession()
await signIn.email({ email, password }, { onSuccess: () => navigateTo('/') })
// 服务器：requireUserSession()
const { user } = await requireUserSession(event, { user: { role: 'admin' } })
// nuxt.config.ts：路由保护
routeRules: {
'/admin/**': { auth: { user: { role: 'admin' } } },
'/login': { auth: 'guest' },
'/app/**': { auth: 'user' }
}
资源
令牌效率：主要技能约300令牌，每个子文件约800-1200令牌