用途
该技能面向使用 Better Auth 进行认证集成的场景，用于指导配置 Better Auth 服务端与客户端、设置数据库适配器、管理会话、添加插件以及处理环境变量。当用户在对话中提到相关需求时适用。
文档版本选择
应使用与项目所装 Better Auth 版本匹配的文档，因为 API 与插件名称在不同维护版本线之间可能不同。优先使用用户明确指定的版本；否则检查 lockfile 中解析出的 better-auth 版本，在没有 lockfile 时回退到包清单。
当 Better Auth MCP 可用时，调用 get_doc 并传入 /llms.txt，将该包版本解析为文档标识符；将标识符传给每次 search_docs 调用，并将结果路径原样传给 get_doc。没有 MCP 时，从 better-auth.com/llms.txt 开始并跟随匹配的版本索引。仅当无法确定项目版本，或用户明确询问最新版本或升级时，才使用最新文档。规划升级时，应将当前已安装版本的指引与目标版本的指引分开。
环境变量
- BETTER_AUTH_SECRET：加密密钥，至少 32 个字符。生成命令：openssl rand -base64 32
- BETTER_AUTH_URL：基础 URL，例如 https://example.com
仅当环境变量未设置时，才在配置中定义 baseURL/secret。
安装与设置工作流
- 安装：npm install better-auth
- 设置环境变量：BETTER_AUTH_SECRET 和 BETTER_AUTH_URL
- 创建 auth.ts，包含数据库与配置
- 为所用框架创建路由处理器
- 运行迁移：
- 内置适配器：npx auth@latest migrate
- Drizzle：npx auth@latest generate --output src/db/auth-schema.ts，然后 npx drizzle-kit push（开发）或 npx drizzle-kit generate && npx drizzle-kit migrate（生产）
- Prisma：npx auth@latest generate --output prisma/schema.prisma，然后 npx prisma migrate dev
- 验证：调用 GET /api/auth/ok，应返回 { status: "ok" }
文件位置与 CLI 命令
CLI 会在 ./、./lib、./utils 或 ./src 下查找 auth.ts，可用 --config 指定自定义路径。
CLI 命令：
- npx auth@latest migrate：应用 schema（内置适配器）
- npx auth@latest generate：为 Prisma/Drizzle 生成 schema
- npx auth@latest mcp --cursor：将 MCP 添加到 AI 工具
在添加或更改插件后需要重新运行。
核心配置项
appName（可选显示名称）、baseURL（仅当未设置 BETTER_AUTH_URL 时）、basePath（默认 /api/auth，设为 / 表示根路径）、secret（仅当未设置 BETTER_AUTH_SECRET 时）、database（多数功能必需）、secondaryStorage（用于会话与限流的 Redis/KV）、emailAndPassword（{ enabled: true } 激活）、socialProviders（如 google 的 clientId/clientSecret）、plugins（插件数组）、trustedOrigins（CSRF 白名单）。
数据库
直连方式：传入 pg.Pool、mysql2 连接池、better-sqlite3 或 bun:sqlite 实例；Postgres 还支持 postgres（postgres.js）与 @neondatabase/serverless。
ORM 适配器从 better-auth/adapters/drizzle、better-auth/adapters/prisma、better-auth/adapters/mongodb 导入。Drizzle 的 provider 取值："pg"（PostgreSQL）、"mysql"（MySQL）、"sqlite"（SQLite），必须与所用驱动匹配。
关键点：Better Auth 使用适配器模型名，而非底层表名。若 Prisma 模型为 User 且映射到表 users，应使用 modelName: "user"（Prisma 引用），而不是 "users"。
会话管理
存储优先级：若定义了 secondaryStorage，会话存于其中（而非数据库）；设置 session.storeSessionInDatabase: true 可同时持久化到数据库；没有数据库且启用 cookieCache 时为完全无状态模式。
Cookie 缓存策略：compact（默认，Base64url + HMAC，体积最小）、jwt（标准 JWT，可读但已签名）、jwe（加密，最高安全性）。
关键选项：session.expiresIn（默认 7 天）、session.updateAge（刷新间隔）、session.cookieCache.maxAge、session.cookieCache.version（更改以使所有会话失效）。
用户与账户配置
用户：user.modelName、user.fields（列映射）、user.additionalFields、user.changeEmail.enabled（默认禁用）、user.deleteUser.enabled（默认禁用）。
账户：account.modelName、account.accountLinking.enabled、account.storeAccountCookie（用于无状态 OAuth）。
注册必需字段：email 和 name。
邮件流程
emailVerification.sendVerificationEmail（必须定义验证才生效）、emailVerification.sendOnSignUp / sendOnSignIn（自动发送触发）、emailAndPassword.sendResetPassword（密码重置邮件处理）。
安全
advanced 中：useSecureCookies（强制 HTTPS Cookie）、disableCSRFCheck（⚠️ 安全风险）、disableOriginCheck（⚠️ 安全风险）、crossSubDomainCookies.enabled（跨子域共享 Cookie）、ipAddress.ipAddressHeaders（代理的自定义 IP 头）、database.generateId（自定义 ID 生成或 "serial"/"uuid"/false）。
限流：rateLimit.enabled、rateLimit.window、rateLimit.max、rateLimit.storage（"memory" | "database" | "secondary-storage"）。
Hooks
端点 Hooks：hooks.before / hooks.after，为 { matcher, handler } 数组，使用 createAuthMiddleware，可访问 ctx.path、ctx.context.returned（after）、ctx.context.session。
数据库 Hooks：databaseHooks.user.create.before/after，session、account 同理，适合添加默认值或创建后操作。
Hook 上下文（ctx.context）：session、secret、authCookies、password.hash()/verify()、adapter、internalAdapter、generateId()、tables、baseURL。
插件
从专用路径导入以支持 tree-shaking，例如 import { twoFactor } from "better-auth/plugins/two-factor"，而不是从 "better-auth/plugins" 导入。
常用插件：twoFactor、organization、passkey、magicLink、emailOtp、username、phoneNumber、admin、apiKey、bearer、jwt、multiSession、sso、oauthProvider、oidcProvider、openAPI、genericOAuth。
客户端插件放在 createAuthClient({ plugins: [...] })。
客户端
导入来源：better-auth/client（vanilla）、better-auth/react、better-auth/vue、better-auth/svelte、better-auth/solid。
关键方法：signUp.email()、signIn.email()、signIn.social()、signOut()、useSession()、getSession()、revokeSession()、revokeSessions()。
类型安全
类型推断：typeof auth.$Infer.Session、typeof auth.$Infer.Session.user。客户端与服务端分离项目：createAuthClient<typeof auth>()。
常见注意事项
模型名与表名（配置使用 ORM 模型名而非数据库表名）、插件 schema（添加插件后重新运行 CLI）、二级存储（会话默认存于其中而非数据库）、Cookie 缓存（自定义会话字段不被缓存，始终重新获取）、无状态模式（无数据库时会话仅在 Cookie 中，缓存过期即登出）、更改邮箱流程（先发送到当前邮箱，再发送到新邮箱）、Drizzle 数据库未初始化（drizzleAdapter(db, ...) 需要来自 drizzle() 的 db 实例，参见 create-auth 技能的设置示例 node-postgres、postgres.js、Neon）、Drizzle 缺少 drizzle.config.ts（drizzle-kit 命令需要 drizzle.config.ts 指向生成的 schema 文件与数据库凭据）。
限制
本技能的官方文本为空，以上内容均整理自所提供的技能说明；关于价格、平台支持范围、具体效果等信息资料中暂未提供。