create-auth

创建 Auth 技能

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

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

---

阶段 1：规划（实施前必做）

编写任何代码之前，请先扫描项目并向用户提出结构化问题，以收集需求。这能确保实施方案符合他们的需求。

步骤 1：扫描项目

分析代码库以自动检测：

• 框架 — 查找 next.config、svelte.config、nuxt.config、astro.config、vite.config 或 Express/Hono 入口文件。
• 数据库/ORM — 查找 prisma/schema.prisma、drizzle.config.ts、package.json 依赖项（pg、postgres、@neondatabase/serverless、mysql2、better-sqlite3、mongoose、mongodb）。如果存在 drizzle.config.ts，请读取其 dialect 字段以确定数据库类型（例如，"postgresql" → Drizzle + Postgres）。还要检查安装了哪个 Drizzle 驱动（drizzle-orm/node-postgres → pg，drizzle-orm/postgres-js → postgres，drizzle-orm/neon-http → Neon）。
• 现有身份验证 — 在 package.json 或导入语句中查找现有身份验证库（next-auth、lucia、clerk、supabase/auth、firebase/auth）。
• 包管理器 — 检查是否存在 pnpm-lock.yaml、yarn.lock、bun.lockb 或 package-lock.json。

根据发现的信息预填默认值，并跳过已能回答的问题。

步骤 2：询问规划问题

使用 AskQuestion 工具，在一次调用中向用户询问所有适用的问题。跳过扫描后已有明确答案的问题。将问题归入类似“身份验证设置规划”的标题下。

要询问的问题：

1. 项目类型（检测到时跳过）

   • 提示：“这是什么类型的项目？”
   • 选项：从零开始创建新项目 | 为现有项目添加身份验证 | 从其他身份验证库迁移

2. 框架（检测到时跳过）

   • 提示：“你使用的是哪个框架？”
   • 选项：Next.js（App Router） | Next.js（Pages Router） | SvelteKit | Nuxt | Astro | Express | Hono | SolidStart | 其他

3. 数据库和 ORM（检测到时跳过）

   • 提示：“你会使用哪种数据库配置？”
   • 选项：PostgreSQL（Prisma） | PostgreSQL（Drizzle） | PostgreSQL（pg 驱动） | MySQL（Prisma） | MySQL（Drizzle） | MySQL（mysql2 驱动） | SQLite（Prisma） | SQLite（Drizzle） | SQLite（better-sqlite3 驱动） | MongoDB（Mongoose） | MongoDB（原生驱动）

4. 身份验证方式（始终询问，允许多选）

   • 提示：“你需要哪些登录方式？”
   • 选项：电子邮件和密码 | 社交 OAuth（Google、GitHub 等） | 魔法链接（无密码电子邮件） | Passkey（WebAuthn） | 手机号
   • allow_multiple: true

5. 社交服务提供商（仅当用户在上面选择了社交 OAuth 时才询问——在后续调用中询问）

   • 提示：“你需要哪些社交服务提供商？”
   • 选项：Google | GitHub | Apple | Microsoft | Discord | Twitter/X
   • allow_multiple: true

6. 电子邮件验证（仅当用户在上面选择了电子邮件和密码时才询问——在后续调用中询问）

   • 提示：“你希望要求进行电子邮件验证吗？”
   • 选项：是 | 否

7. 电子邮件服务提供商（仅当电子邮件验证为“是”，或在功能中选择了密码重置时才询问——在后续调用中询问）

   • 提示：“你希望如何发送电子邮件？”
   • 选项：Resend | 暂时模拟（console.log）

8. 功能和插件（始终询问，允许多选）

   • 提示：“你还需要哪些功能？”
   • 选项：双重身份验证（2FA） | 组织/团队 | 管理员仪表盘 | API bearer 令牌 | 密码重置 | 都不需要
   • allow_multiple: true

9. 身份验证页面（始终询问，允许多选——根据前面的回答预选）

   • 提示：“你需要哪些身份验证页面？”
   • 选项根据前面的回答而有所不同：
     • 始终可选：登录 | 注册
     • 如果选择了电子邮件和密码：忘记密码 | 重置密码
     • 如果启用了电子邮件验证：电子邮件验证
   • allow_multiple: true

10. 身份验证界面风格（始终询问）

• 提示：“你希望身份验证页面采用什么风格？请选择一种，或描述你自己的风格。”
• 选项：简约干净 | 带背景的居中卡片 | 分栏布局（表单 + 主视觉图片） | 悬浮/玻璃拟态 | 其他（我会描述）

步骤 3：总结计划

收集完回答后，以 Markdown 复选清单的形式简要呈现实施计划。例如：

## Auth Implementation Plan

- **Framework:** Next.js (App Router)
- **Database:** PostgreSQL via Prisma
- **Auth methods:** Email/password, Google OAuth, GitHub OAuth
- **Plugins:** 2FA, Organizations, Email verification
- **UI:** Custom forms

### Steps
1. Install `better-auth` (the CLI ships as the `auth` package and is run via `npx auth@latest`, no install needed)
2. Create `lib/auth.ts` with server config
3. Create `lib/auth-client.ts` with React client
4. Set up route handler at `app/api/auth/[...all]/route.ts`
5. Configure Prisma adapter and generate schema
6. Add Google & GitHub OAuth providers
7. Enable `twoFactor` and `organization` plugins
8. Set up email verification handler
9. Run migrations
10. Create sign-in / sign-up pages

请用户确认计划后再继续进入第 2 阶段。

---

第 2 阶段：实施

仅在用户确认第 1 阶段的计划后，才继续此阶段。

根据下方的决策树，并结合上面收集的回答进行操作。

Is this a new/empty project?
├─ YES → New project setup
│   1. Install better-auth (+ scoped packages per plan)
│   2. Create auth.ts with all planned config
│   3. Create auth-client.ts with framework client
│   4. Set up route handler
│   5. Set up environment variables
│   6. Run CLI migrate/generate
│   7. Add plugins from plan
│   8. Create auth UI pages
│
├─ MIGRATING → Migration from existing auth
│   1. Audit current auth for gaps
│   2. Plan incremental migration
│   3. Install better-auth alongside existing auth
│   4. Migrate routes, then session logic, then UI
│   5. Remove old auth library
│   6. See migration guides in docs
│
└─ ADDING → Add auth to existing project
    1. Analyze project structure
    2. Install better-auth
    3. Create auth config matching plan
    4. Add route handler
    5. Run schema migrations
    6. Integrate into existing pages
    7. Add planned plugins and features

实施结束时，详细指导用户完成剩余后续步骤（例如，设置 OAuth 应用凭据、部署环境变量、测试流程）。

---

安装

核心包： 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 auth@latest migrate（直接应用）
Prisma	npx auth@latest generate --output prisma/schema.prisma 然后运行 npx prisma migrate dev
Drizzle（开发）	npx auth@latest generate --output src/db/auth-schema.ts 然后运行 npx drizzle-kit push
Drizzle（生产）	npx auth@latest generate --output src/db/auth-schema.ts 然后运行 npx drizzle-kit generate，再运行 npx drizzle-kit migrate

注意： drizzle-kit push 会跳过迁移文件，仅适用于开发环境。在生产环境中，请使用 drizzle-kit generate + drizzle-kit migrate。

添加插件后请重新运行。

---

数据库适配器

数据库	设置
SQLite	直接传入 better-sqlite3 或 bun:sqlite 实例
PostgreSQL	直接传入 pg.Pool 实例
MySQL	直接传入 mysql2 连接池
Prisma	从 better-auth/adapters/prisma 导入 prismaAdapter(prisma, { provider: "postgresql" })
Drizzle（pg）	从 better-auth/adapters/drizzle 导入 drizzleAdapter(db, { provider: "pg" })
Drizzle（mysql）	从 better-auth/adapters/drizzle 导入 drizzleAdapter(db, { provider: "mysql" })
Drizzle（sqlite）	从 better-auth/adapters/drizzle 导入 drizzleAdapter(db, { provider: "sqlite" })
MongoDB	从 better-auth/adapters/mongodb 导入 mongodbAdapter(db)

Drizzle + PostgreSQL 设置

使用 drizzleAdapter 前，请初始化 db 实例：

// Option 1: node-postgres (pg)
import { drizzle } from "drizzle-orm/node-postgres"
import { Pool } from "pg"
import * as schema from "./auth-schema"

const pool = new Pool({ connectionString: process.env.DATABASE_URL })
export const db = drizzle(pool, { schema })

// Option 2: postgres.js
import { drizzle } from "drizzle-orm/postgres-js"
import postgres from "postgres"
import * as schema from "./auth-schema"

const client = postgres(process.env.DATABASE_URL!)
export const db = drizzle(client, { schema })

// Option 3: Neon serverless
import { drizzle } from "drizzle-orm/neon-http"
import { neon } from "@neondatabase/serverless"
import * as schema from "./auth-schema"

const sql = neon(process.env.DATABASE_URL!)
export const db = drizzle(sql, { schema })

然后传入 Better Auth：

import { betterAuth } from "better-auth"
import { drizzleAdapter } from "better-auth/adapters/drizzle"
import { db } from "./db"

export const auth = betterAuth({
  database: drizzleAdapter(db, { provider: "pg" }),
  // ...
})

Drizzle 配置（drizzle.config.ts）

drizzle-kit 命令需要此配置才能找到你的 schema：

import { defineConfig } from "drizzle-kit"

export default defineConfig({
  schema: "./src/db/auth-schema.ts",
  out: "./drizzle",
  dialect: "postgresql",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
})

---

常见插件

插件	服务端导入	客户端导入	用途
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
• 迁移指南