用途
nuxt-better-auth 是一个面向 Nuxt 4+ 的认证模块，构建在 Better Auth 之上，通过 @onmax/nuxt-better-auth 提供。它用于在 Nuxt 应用中实现认证相关功能，包括登录、注册、登出流程，客户端与服务端的路由保护，以及在 API 路由中访问用户会话。
该模块当前处于 alpha 阶段（v0.0.2-alpha.19），官方说明其不推荐用于生产环境，API 可能发生变化。
主要能力
- 提供 useUserSession 组合式函数，用于管理用户、会话、loggedIn 状态以及 signIn/signOut 方法。
- 提供服务端助手：serverAuth、getUserSession、requireUserSession。其中 requireUserSession 在未认证时会抛出 401/403，并可按用户属性（如角色）进行限制。
- 支持路由保护，可通过 routeRules、definePageMeta 和中间件实现。auth 路由模式支持 'user'、'guest'、{ user: {...} } 或 false。
- 支持集成 Better Auth 插件，例如 admin、passkey、2FA。
- 支持通过 NuxtHub 集成数据库，并提供 Drizzle schema 与带外键的自定义表相关内容。
- 支持 clientOnly 模式，用于对接外部认证后端（涉及 CORS）。
- 支持配合 @nuxtjs/i18n 添加国际化支持。
使用方式
该技能以参考文档形式组织，包含以下文件与主题：
- 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 插件（admin、passkey、2FA）。
- references/database.md：NuxtHub 集成、Drizzle schema、带外键的自定义表。
- references/client-only.md：外部认证后端、clientOnly 模式、CORS。
- references/types.md：AuthUser、AuthSession、类型增强。
建议根据当前任务仅加载相关文件，不要一次性加载全部文件。
快速参考示例：
客户端使用 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' }
}
相关资源包括 Module Docs 与 Better Auth Docs。该技能的 token 效率说明：主技能约 300 tokens，每个子文件约 800-1200 tokens。
适用场景
- 安装或配置 @onmax/nuxt-better-auth。
- 实现登录、注册、登出流程。
- 保护客户端与服务端路由。
- 在 API 路由中访问用户会话。
- 集成 Better Auth 插件（admin、passkey、2FA）。
- 使用 NuxtHub 搭建数据库。
- 使用 clientOnly 模式对接外部认证后端。
- 配合 @nuxtjs/i18n 添加国际化支持。
相关的 Nuxt 模式请使用 nuxt 技能，NuxtHub 数据库请使用 nuxthub 技能。
限制
该模块处于 alpha 阶段，不推荐用于生产环境，API 可能发生变化。其余关于收费、价格、平台等具体信息暂未提供。