创建认证技能Skill create-auth-skill

---

名称：创建认证技能 description: 在TypeScript/JavaScript应用中使用Better Auth创建认证层的技能

创建认证技能

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

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

---

决策树

这是一个新的/空项目吗？
├─ 是 → 新项目设置
│   1. 识别框架
│   2. 选择数据库
│   3. 安装better-auth
│   4. 创建auth.ts + auth-client.ts
│   5. 设置路由处理器
│   6. 运行CLI迁移/生成
│   7. 通过插件添加功能
│
└─ 否 → 项目是否有现有认证？
    ├─ 是 → 迁移/增强
    │   • 审计当前认证的差距
    │   • 规划增量迁移
    │   • 查看文档中的迁移指南
    │
    └─ 否 → 向现有项目添加认证
        1. 分析项目结构
        2. 安装better-auth
        3. 创建认证配置
        4. 添加路由处理器
        5. 运行模式迁移
        6. 集成到现有页面中

---

安装

核心： npm install better-auth

作用域包（根据需要）：

包	使用场景
@better-auth/passkey	WebAuthn/Passkey认证
@better-auth/sso	SAML/OIDC企业单点登录
@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提供商（谷歌、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 服务器组件： 在认证配置中添加 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	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令牌认证
openAPI	better-auth/plugins	-	API文档
passkey	@better-auth/passkey	passkeyClient	WebAuthn
sso	@better-auth/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

---

故障排除

问题	修复方法
“未设置密钥”	添加 BETTER_AUTH_SECRET 环境变量
“无效来源”	将域名添加到 trustedOrigins
Cookie未设置	检查 baseURL 是否与域名匹配；生产环境中启用安全Cookie
OAuth回调错误	验证提供商仪表板中的重定向URI
添加插件后出现类型错误	重新运行CLI生成/迁移

---

资源

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