关于 better-auth
面向 TypeScript 项目的 Better Auth 实现指南，重点提供 Next.js 16 App Router 的服务端、客户端、会话和路由保护架构。内容涵盖 OAuth、插件、数据库适配器及从其他身份验证方案迁移。
主要功能
- 01配置服务端认证与客户端状态
- 02使用 App Router 认证路由和 proxy.ts
- 03覆盖 40 多种 OAuth 提供方
- 04支持 2FA、Passkey、SSO 等插件
- 05涵盖多种数据库适配器与迁移路径
适用场景
- 01在 Next.js 16 项目中接入身份验证
- 02为应用添加 OAuth 登录和会话管理
- 03配置企业 SSO 或多租户组织
- 04从 Auth.js、Clerk 或其他方案迁移
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/better-auth确认已加载。
详细介绍
涵盖完整功能范围：40 多个 OAuth 提供商（Google、GitHub、Discord、Apple、Microsoft 等）、20 多个插件（2FA、magic links、passkeys、organizations/multi-tenant、enterprise SSO/SAML、SCIM provisioning、Stripe/Polar billing、JWT/Bearer、API keys）和数据库适配器（Prisma、Drizzle、MongoDB、raw SQL）。还涵盖从 Auth.js、Clerk、Auth0、Supabase 和 WorkOS 迁移的路径。Better Auth 本身与框架无关，但此技能中的架构指南（proxy.ts、App Router API 路由）特定于 Next.js；Prisma schema/query 详情请参阅 prisma-7。
Better Auth - 完整身份验证
TypeScript 优先的身份验证库，支持 40 多个 OAuth 提供商和 20 多个插件。
Agent 工作流（强制）
在进行任何实现之前，必须并行启动 3 个 Agent，每个 Agent 调用一次，并指定一个 name：
- fuse-ai-pilot:explore-codebase - 分析现有身份验证设置和模式
- fuse-ai-pilot:research-expert - 通过 Context7/Exa 核实最新的 Better Auth 文档
- mcp__context7__query-docs - 检查提供商/插件的可用情况
实现后，运行 fuse-ai-pilot:sniper 进行验证。
概述
适用场景
- 在 TypeScript/JavaScript 应用中实现身份验证
- 需要 OAuth 提供商（Google、GitHub、Discord、Apple、Microsoft 等）
- 添加 2FA、magic links、passkeys 或电话身份验证
- 使用 SAML、SCIM provisioning 或 organizations 实现企业 SSO
- 集成 Stripe 或 Polar 订阅付款
- 使用 Sign-In with Ethereum（SIWE）实现 Web3 身份验证
- 从 Auth.js、Clerk、Auth0、Supabase 或 WorkOS 迁移
为什么选择 Better Auth
| 功能 | 优势 |
|---|---|
| 与框架无关 | Next.js、SvelteKit、Nuxt、Remix、Astro、Expo、NestJS |
| 插件架构 | 只添加所需功能（20 多个插件） |
| 完整 TypeScript 支持 | 端到端类型安全，包含类型推断 |
| 可自托管 | 数据保留在自己的基础设施上 |
| 灵活的数据库支持 | Prisma、Drizzle、MongoDB、PostgreSQL、MySQL、SQLite |
| 满足企业需求 | SSO、SCIM、organizations、审计日志 |
版本说明（当前稳定版：1.7.x）
| 自版本 | 变更 |
|---|---|
| 1.5 | 独立 CLI npx auth@latest（generate、migrate、secret、init、check…）取代 @better-auth/cli；OAuth 2.1 Provider（@better-auth/oauth-provider） |
| 1.6 | 根据 createdAt 计算 session.freshAge；弃用 oidcProvider |
| 1.7 | 移除 oidcProvider；通用 OAuth 提供商使用 signIn.social（不再使用 genericOAuthClient）；通过 advanced.database.joins 进行数据库联接；账户以 (issuer, accountId) 为键；twoFactor.enable 返回由 method 区分的响应；MCP → @better-auth/mcp；SCIM 与 organization 解耦 |
升级到 1.7 后，重新生成 schema（npx auth@latest generate），并遵循官方 1.7 升级指南。
覆盖范围
OAuth 提供商（40+）
Google、GitHub、Discord、Apple、Microsoft、Slack、Spotify、Twitter/X、Facebook、LinkedIn、GitLab、Bitbucket、Dropbox、Twitch、Reddit、TikTok，以及 providers/ 中记录的 25 多个其他提供商。
插件（20+）
| 插件 | 用途 |
|---|---|
| 2FA | TOTP 验证器、备用代码 |
| Magic Link | 通过电子邮件免密码登录 |
| Passkey | WebAuthn 生物特征身份验证 |
| Organization | 多租户、角色、邀请 |
| SSO | 企业 SAML/OIDC 单点登录 |
| SCIM | 目录同步、用户 provisioning |
| Stripe | 订阅计费集成 |
| API Key | 机器到机器身份验证 |
| JWT/Bearer | 基于令牌的 API 身份验证 |
数据库适配器
Prisma、Drizzle、MongoDB、raw SQL（PostgreSQL、MySQL、SQLite）和社区适配器。
SOLID 架构（Next.js 16）
组件按关注点分离原则组织在 modules/auth/ 中：
- 服务：
betterAuth配置和初始化 - Hooks：用于客户端身份验证状态的
createAuthClient - API 路由：
app/api/auth/[...all]/route.ts处理程序 - 代理：用于路由保护的
proxy.ts（替代 middleware）
参考指南
| 需求 | 参考资料 |
|---|---|
| 初始设置 | installation.md、server-config.md |
| 客户端用法 | client.md、session.md |
| OAuth 提供商 | providers/overview.md、各提供商的文档 |
| 添加插件 | plugins/overview.md、各插件的文档 |
| 数据库设置 | adapters/prisma.md、adapters/drizzle.md |
| 企业级 SSO | plugins/sso.md、guides/saml-okta.md |
| 付款 | plugins/stripe.md、plugins/polar.md |
| 迁移 | guides/clerk-migration.md、其他迁移指南 |
| 完整示例 | examples/ 中的完整实现 |
最佳实践
- 按需使用插件 - 仅添加实际需要的插件
- 类型安全的客户端 - 使用从服务端配置生成的类型
- 会话缓存 - 启用会话缓存以提升性能
- 速率限制 - 为身份验证端点配置速率限制
- 安全 Cookie - 使用 secure、httpOnly、sameSite Cookie
- 数据库索引 - 在用户查询字段上添加索引
概念
concepts/ 中介绍了核心概念：
- 会话 - 令牌管理、刷新、撤销
- 数据库 - 架构设计、迁移、适配器
- 插件 - 扩展系统、组合
- OAuth - 提供商配置、回调
- 安全 - CSRF、速率限制、密码哈希
- Cookie - 会话存储、跨域