Create Auth Skill

使用 Better Auth 为 TypeScript/JavaScript 应用添加鉴权的指南。

代码示例与语法参见 better-auth.com/docs。

决策树

是否为新项目/空项目？
├─ 是 → 新项目搭建
│ 1. 确定框架
│ 2. 选择数据库
│ 3. 安装 better-auth
│ 4. 创建 auth.ts + auth-client.ts
│ 5. 配置路由处理器
│ 6. 运行 CLI migrate/generate
│ 7. 通过插件添加能力
│
└─ 否 → 项目是否已有鉴权？
 ├─ 是 → 迁移/增强
 │ • 审计现有鉴权缺口
 │ • 规划渐进式迁移
 │ • 参考文档中的迁移指南
 │
 └─ 否 → 为现有项目添加鉴权
 1. 分析项目结构
 2. 安装 better-auth
 3. 创建 auth 配置
 4. 添加路由处理器
 5. 运行 schema 迁移
 6. 接入现有页面

安装

核心： npm install better-auth

按需安装的作用域包：

包	用途
`@better-auth/passkey`	WebAuthn/Passkey 鉴权
`@better-auth/sso`	SAML/OIDC 企业 SSO
`@better-auth/stripe`	Stripe 支付
`@better-auth/scim`	SCIM 用户配置
`@better-auth/expo`	React Native/Expo

环境变量

BETTER_AUTH_SECRET=<32+ 字符，可用 openssl rand -base64 32 生成>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=

按需添加 OAuth 密钥：GITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET、GOOGLE_CLIENT_ID 等。

服务端配置（auth.ts）

位置： lib/auth.ts 或 src/lib/auth.ts

最小配置需包含：

database - 连接或适配器
emailAndPassword: { enabled: true } - 邮箱/密码鉴权

标准配置可增加：

socialProviders - OAuth 提供方（google、github 等）
emailVerification.sendVerificationEmail - 验证邮件发送
emailAndPassword.sendResetPassword - 重置密码发送

完整配置可增加：

plugins - 功能插件数组
session - 过期、cookie 缓存等
account.accountLinking - 多提供方账号关联
rateLimit - 限流配置

导出类型： export type Session = typeof auth.$Infer.Session

客户端配置（auth-client.ts）

按框架导入：

框架	导入
React/Next.js	`better-auth/react`
Vue	`better-auth/vue`
Svelte	`better-auth/svelte`
Solid	`better-auth/solid`
Vanilla JS	`better-auth/client`

客户端插件 放在 createAuthClient({ plugins: [...] }) 中。

常用导出： signIn、signUp、signOut、useSession、getSession

路由处理器配置

框架	文件	处理器
Next.js App Router	`app/api/auth/[...all]/route.ts`	`toNextJsHandler(auth)` → 导出 `{ GET, POST }`
Next.js Pages	`pages/api/auth/[...all].ts`	`toNextJsHandler(auth)` → 默认导出
Express	任意文件	`app.all("/api/auth/*", toNodeHandler(auth))`
SvelteKit	`src/hooks.server.ts`	`svelteKitHandler(auth)`
SolidStart	路由文件	`solidStartHandler(auth)`
Hono	路由文件	`auth.handler(c.req.raw)`

Next.js Server Components： 在 auth 配置中添加 nextCookies() 插件。

数据库迁移

适配器	命令
内置 Kysely	`npx @better-auth/cli@latest migrate`（直接应用）
Prisma	`npx @better-auth/cli@latest generate --output prisma/schema.prisma` 然后 `npx prisma migrate dev`
Drizzle	`npx @better-auth/cli@latest generate --output src/db/auth-schema.ts` 然后 `npx drizzle-kit push`

添加插件后需重新执行。

数据库适配器

数据库	配置
SQLite	直接传入 `better-sqlite3` 或 `bun:sqlite` 实例
PostgreSQL	直接传入 `pg.Pool` 实例
MySQL	直接传入 `mysql2` pool
Prisma	`prismaAdapter(prisma, { provider: "postgresql" })`，来自 `better-auth/adapters/prisma`
Drizzle	`drizzleAdapter(db, { provider: "pg" })`，来自 `better-auth/adapters/drizzle`
MongoDB	`mongodbAdapter(db)`，来自 `better-auth/adapters/mongodb`

常用插件

插件	服务端导入	客户端导入	用途
`twoFactor`	`better-auth/plugins`	`twoFactorClient`	TOTP/OTP 双因素
`organization`	`better-auth/plugins`	`organizationClient`	团队/组织
`admin`	`better-auth/plugins`	`adminClient`	用户管理
`bearer`	`better-auth/plugins`	-	API Token 鉴权
`openAPI`	`better-auth/plugins`	-	API 文档
`passkey`	`@better-auth/passkey`	`passkeyClient`	WebAuthn
`sso`	`@better-auth/sso`	-	企业 SSO

插件用法： 服务端插件 + 客户端插件 + 执行迁移。

鉴权 UI 实现

登录流程：

signIn.email({ email, password }) 或 signIn.social({ provider, callbackURL })
处理返回的 error
成功时重定向

客户端会话检查： useSession() 返回 { data: session, isPending }

服务端会话检查： auth.api.getSession({ headers: await headers() })

受保护路由： 检查 session，为空则重定向到 /sign-in。

安全清单

故障排查

问题	处理
"Secret not set"	添加 `BETTER_AUTH_SECRET` 环境变量
"Invalid Origin"	在 `trustedOrigins` 中加入域名
Cookie 不生效	检查 `baseURL` 与域名一致；生产启用 secure cookies
OAuth 回调错误	在提供方控制台核对 redirect URIs
添加插件后类型报错	重新运行 CLI generate/migrate