【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载导读本文以 autoskills 技能仓库中的 best-practices/SKILL.md 为核心骨架系统讲解 Better Auth 的完整接入流程从安装、环境变量、数据库适配器、会话管理、用户与账户模型、邮箱流程、安全加固、钩子Hooks、插件体系到客户端接入与类型安全并结合 skills-map.ts 中 Better Auth 的自动检测与技能挂载逻辑说明该技能在 autoskills 项目中的实际定位。读完本文你将能够独立完成一个具备邮箱/密码登录、OAuth、2FA、组织与 RBAC 的 TypeScript 认证系统并避开模型名/表名混用、插件 schema 未同步等高频坑。背景Better Auth 在 autoskills 技能体系中的定位autoskills 是一个一条命令安装整套 AI 技能栈的工具它扫描项目的package.json、锁文件与配置文件自动识别技术栈并安装对应的 Agent 技能。在 skills-map.ts 中better-auth通过packages: [better-auth]被识别并挂载四个技能better-auth/skills/best-practices本文主体better-auth/skills/emailAndPasswordbetter-auth/skills/organizationbetter-auth/skills/twoFactor这些技能文件最终被安装到.claude/skills等目录下供 AI 编码助手在开发认证功能时自动查阅。而仓库中的 validate-registry.mjs 会逐文件校验技能清单的 SHA-256 哈希与 bundleHash确保安装到用户项目的技能内容与注册表完全一致。这意味着本文所述配置方式就是 Better Auth 官方技能所推荐的标准做法。标准接入工作流按以下六步即可完成 Better Auth 的最小可用接入安装依赖npm install better-auth设置环境变量BETTER_AUTH_SECRET与BETTER_AUTH_URL创建auth.ts配置数据库与核心选项为你的框架创建路由处理器route handler执行npx better-auth/clilatest migrate同步数据库 schema验证调用GET /api/auth/ok应返回{ status: ok }其中第 3、4 步因框架而异——Next.js 使用 Route HandlerHono/Express 使用中间件Astro 使用 Server Endpoint。CLI 会自动在以下位置寻找auth.ts./、./lib、./utils、./src如果你的文件放在其他位置用--config指定自定义路径。环境变量变量说明BETTER_AUTH_SECRET加密密钥最少 32 个字符。生成命令openssl rand -base64 32BETTER_AUTH_URL基础 URL例如https://example.com只有在环境变量未设置时才需要在配置中显式定义baseURL与secret。这一约定避免了密钥硬编码进源码也便于在不同环境开发/预发/生产间切换。CLI 常用命令命令作用npx better-auth/clilatest migrate为内置数据库适配器应用 schemanpx better-auth/clilatest generate为 Prisma / Drizzle 生成 schema 文件npx better-auth/cli mcp --cursor将 Better Auth 作为 MCP 接入 AI 工具重要每当你新增或修改插件后都必须重新运行上述 CLI 命令否则新增表/字段不会同步到数据库。核心配置选项betterAuth()接受一个配置对象常用选项如下选项说明appName可选用于显示的应用名baseURL仅在未设置BETTER_AUTH_URL时使用basePath默认/api/auth设为/可挂载到根路径secret仅在未设置BETTER_AUTH_SECRET时使用database大多数功能必需详见下方数据库章节secondaryStorageRedis/KV用于会话与限流emailAndPassword设为{ enabled: true }激活邮箱密码登录socialProviders例如{ google: { clientId, clientSecret }, ... }plugins插件数组trustedOriginsCSRF 白名单一个带邮箱密码登录的最小配置import { betterAuth } from better-auth; export const auth betterAuth({ appName: My App, emailAndPassword: { enabled: true }, socialProviders: { github: { clientId: ..., clientSecret: ... }, }, });数据库连接与 ORM 适配器直接连接直接传入数据库实例即可——import { Pool } from pg; // 或 mysql2 pool / better-sqlite3 / bun:sqlite export const auth betterAuth({ database: new Pool({ connectionString: process.env.DATABASE_URL }), });ORM 适配器分别从better-auth/adapters/drizzle、better-auth/adapters/prisma、better-auth/adapters/mongodb导入。关键陷阱模型名 ≠ 表名Better Auth 使用适配器的模型名而非底层表名。例如 Prisma 中 model 叫User、映射到表users时配置里应写modelName: userPrisma 引用名不要写users。这一错误是最常见的接入失败原因之一。会话管理Better Auth 的会话存储遵循以下优先级定义了secondaryStorage→ 会话存放在 Redis/KV 中不再进数据库设置session.storeSessionInDatabase: true→ 额外持久化到数据库无数据库 cookieCache→ 完全无状态stateless模式Cookie 缓存策略策略特点compact默认Base64url HMAC体积最小jwt标准 JWT可读但已签名jwe加密存储安全性最高关键会话选项session.expiresIn默认 7 天session.updateAge会话刷新间隔session.cookieCache.maxAgecookie 缓存存活时间session.cookieCache.version变更该值可使所有会话失效配置示例export const auth betterAuth({ session: { expiresIn: 60 * 60 * 24 * 7, // 7 天 updateAge: 60 * 60 * 24, // 每天刷新 cookieCache: { enabled: true, maxAge: 60 * 5, // 5 分钟 strategy: jwt, }, }, secondaryStorage: redisStorage, // 你的 Redis 适配器 });用户与账户配置用户Useruser.modelName模型名、user.fields列映射、user.additionalFields附加字段、user.changeEmail.enabled默认关闭、user.deleteUser.enabled默认关闭。账户Accountaccount.modelName、account.accountLinking.enabled账号关联、account.storeAccountCookie无状态 OAuth 场景。注册必需字段email和name。为 User 增加自定义字段export const auth betterAuth({ user: { additionalFields: { plan: { type: string, required: false }, }, }, });邮箱流程配置项作用emailVerification.sendVerificationEmail必须定义验证功能才会生效emailVerification.sendOnSignUp/sendOnSignIn注册/登录时自动发送验证邮件emailAndPassword.sendResetPassword密码重置邮件处理器完整的邮箱验证配置更深入的 email/password 流程可参考同仓库的 emailAndPassword/SKILL.mdimport { betterAuth } from better-auth; export const auth betterAuth({ emailVerification: { sendOnSignUp: true, sendVerificationEmail: async ({ user, url, token }) { await sendEmail({ to: user.email, subject: Verify your email, text: Click to verify: ${url}, }); }, }, emailAndPassword: { sendResetPassword: async ({ user, url }) { await sendEmail({ to: user.email, subject: Reset your password, text: Click to reset: ${url}, }); }, }, });安全加固advanced 选项选项说明useSecureCookies强制 HTTPS CookiedisableCSRFCheck⚠️ 安全风险通常不建议disableOriginCheck⚠️ 安全风险通常不建议crossSubDomainCookies.enabled跨子域共享 CookieipAddress.ipAddressHeaders代理场景下自定义 IP 头database.generateId自定义 ID 生成或serial/uuid/false限流Rate Limitingexport const auth betterAuth({ rateLimit: { enabled: true, window: 60, // 窗口秒数 max: 100, // 窗口内最大请求数 storage: secondary-storage, // memory | database | secondary-storage }, });钩子Hooks端点钩子hooks.before/hooks.after是{ matcher, handler }数组处理器用createAuthMiddleware创建。在ctx上可访问ctx.path、ctx.context.returnedafter 阶段、ctx.context.session。数据库钩子databaseHooks.user.create.before/aftersession、account同理适合注入默认值或执行创建后动作。钩子上下文ctx.context可用成员session、secret、authCookies、password.hash()/password.verify()、adapter、internalAdapter、generateId()、tables、baseURL。一个 after 钩子示例为新建用户附加默认数据export const auth betterAuth({ databaseHooks: { user: { create: { after: async (user) { await createDefaultResources(user.id); }, }, }, }, });插件体系为支持 tree-shaking插件必须从专用路径导入import { twoFactor } from better-auth/plugins/two-factor; // ✅ // import { twoFactor } from better-auth/plugins; // ❌常用插件twoFactor、organization、passkey、magicLink、emailOtp、username、phoneNumber、admin、apiKey、bearer、jwt、multiSession、sso、oauthProvider、oidcProvider、openAPI、genericOAuth。客户端插件放进createAuthClient({ plugins: [...] })。服务端与客户端的两个完整插件示例2FA 与组织见同仓库的 twoFactor/SKILL.md 与 organization/SKILL.md。组合示例如下import { betterAuth } from better-auth; import { twoFactor } from better-auth/plugins/two-factor; import { organization } from better-auth/plugins/organization; export const auth betterAuth({ appName: My App, plugins: [twoFactor({ issuer: My App }), organization()], });客户端接入按框架从对应入口导入原生better-auth/clientReactbetter-auth/reactVuebetter-auth/vueSveltebetter-auth/svelteSolidbetter-auth/solidimport { createAuthClient } from better-auth/react; export const authClient createAuthClient(); // 登录 / 注册 / 登出 await authClient.signUp.email({ email, password, name }); await authClient.signIn.email({ email, password }); await authClient.signIn.social({ provider: google }); await authClient.signOut(); // 会话 const { data: session } await authClient.getSession(); const { data } await authClient.useSession(); // 会话撤销 await authClient.revokeSession({ token }); await authClient.revokeSessions();类型安全从服务端配置推断类型type Session typeof auth.$Infer.Session; type SessionUser typeof auth.$Infer.Session.user;当客户端与服务端分属不同项目时用泛型关联import { createAuthClient } from better-auth/react; import type { auth } from ./server/auth; export const authClient createAuthClienttypeof auth();常见陷阱Gotchas模型名 vs 表名配置使用 ORM 模型名如user不是数据库表名如users插件 schema新增插件后必须重新运行 CLImigrate/generateSecondary storage定义了它之后会话默认存到 KV/Redis 而非数据库Cookie 缓存自定义 session 字段不会被缓存总是重新获取无状态模式无数据库时会话只存在于 Cookie 中缓存过期即登出改邮箱流程先发到当前邮箱验证再发到新邮箱小结与延伸阅读本文覆盖了 Better Auth 从安装、配置、数据库、会话、邮箱、安全、钩子、插件到客户端与类型安全的完整链路。想深入具体能力可继续阅读同仓库的关联技能文档emailAndPassword/SKILL.md密码策略、重置与 Argon2id、twoFactor/SKILL.mdTOTP/OTP/备用码与 organization/SKILL.md多租户组织与 RBAC。在 autoskills 中只需npx autoskills项目检测到better-auth依赖后即会自动安装以上全部技能并可由 validate-registry.mjs 校验的内容确保与官方技能完全一致。赞分享【免费下载链接】autoskillsOne command. Your entire AI skill stack. Installed.项目地址https://gitcode.com/gh_mirrors/au/autoskills点击查看免费下载相关推荐Better Auth 实战集成指南TypeScript 全栈认证框架配置要点与 Novu 仓库落地实践Better Auth 实战集成指南TypeScript 全栈认证框架配置要点与 Novu 仓库落地实践 Better Auth 是 TypeScript f后端消息路由前端通信AI Agent最速认证方案Better AuthElysiaBun全栈集成指南最速认证方案Better AuthElysiaBun全栈集成指南 你还在为TypeScript项目的认证模块性能发愁还在忍受传统框架的启动延迟本文将带认证鉴权后端身份认证5分钟搞定Vue全栈认证Better Auth无缝集成Nuxt实战指南5分钟搞定Vue全栈认证Better Auth无缝集成Nuxt实战指南 你还在为Vue全栈应用的身份验证头疼吗配置繁琐、兼容性差、安全性难保障本文将带你用认证鉴权后端身份认证上一篇游戏下载加速终极指南用 Hydra 把等大作的夜晚彻底省下来下一篇closure-compiler与月球基地技术突破优化地外Web应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考