create-auth-skill

创建身份验证 Skill

使用 Better Auth 为 TypeScript/JavaScript 应用添加身份验证的指南。

代码示例和语法请参阅 better-auth.com/docs。

---

决策树

Is this a new/empty project?
├─ YES → New project setup
│   1. Identify framework
│   2. Choose database
│   3. Install better-auth
│   4. Create auth.ts + auth-client.ts
│   5. Set up route handler
│   6. Run CLI migrate/generate
│   7. Add features via plugins
│
└─ NO → Does project have existing auth?
    ├─ YES → Migration/enhancement
    │   • Audit current auth for gaps
    │   • Plan incremental migration
    │   • See migration guides in docs
    │
    └─ NO → Add auth to existing project
        1. Analyze project structure
        2. Install better-auth
        3. Create auth config
        4. Add route handler
        5. Run schema migrations
        6. Integrate into existing pages

---

安装

核心包： 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+ chars, generate with: openssl rand -base64 32>
BETTER_AUTH_URL=http://localhost:3000
DATABASE_URL=<your database connection string>

按需添加 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： 将 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 连接池
Prisma	使用 better-auth/adapters/prisma 中的 prismaAdapter(prisma, { provider: "postgresql" })
Drizzle	使用 better-auth/adapters/drizzle 中的 drizzleAdapter(db, { provider: "pg" })
MongoDB	使用 better-auth/adapters/mongodb 中的 mongodbAdapter(db)

---

常见插件

插件	服务端导入	客户端导入	用途
twoFactor	better-auth/plugins	twoFactorClient	使用 TOTP/OTP 进行双重身份验证
organization	better-auth/plugins	organizationClient	团队/组织
admin	better-auth/plugins	adminClient	用户管理
bearer	better-auth/plugins	-	API 令牌身份验证
openAPI	better-auth/plugins	-	API 文档
passkey	@better-auth/passkey	passkeyClient	WebAuthn
sso	@better-auth/sso	-	企业 SSO

插件模式： 服务端插件 + 客户端插件 + 运行迁移。

---

身份验证 UI 实现

登录流程：

1. signIn.email({ email, password }) 或 signIn.social({ provider, callbackURL })
2. 处理响应中的 error
3. 成功后重定向

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

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

受保护的路由： 检查会话；如果为 null，则重定向到 /sign-in。

---

安全检查清单

• 已设置 BETTER_AUTH_SECRET（至少 32 个字符）
• 在生产环境中设置 advanced.useSecureCookies: true
• 已配置 trustedOrigins
• 已启用速率限制
• 已启用电子邮件验证
• 已实现密码重置
• 敏感应用已启用双重身份验证
• 未禁用 CSRF 保护
• 已检查 account.accountLinking

---

故障排除

问题	解决方法
"Secret not set"	添加 BETTER_AUTH_SECRET 环境变量
"Invalid Origin"	将域名添加到 trustedOrigins
未设置 Cookie	检查 baseURL 是否与域名匹配；在生产环境中启用安全 Cookie
OAuth 回调错误	在提供商控制台中验证重定向 URI
添加插件后出现类型错误	重新运行 CLI generate/migrate

---

资源

• 文档
• 示例
• 插件
• CLI
• 迁移指南