# 更好的认证 **软件包**：better-auth@1.4.15（自 v1.4.0 起仅限 ESM）**文档**： | **GitHub**： ## 环境设置变量|目的 ---|--- `BETTER_AUTH_SECRET` |加密秘密（最少 32 个字符）。生成：`openssl rand -base64 32` `BETTER_AUTH_URL` |基本 URL（例如“https://example.com”）如果未设置环境变量，则仅在配置中定义“baseURL”/“secret”。 CLI 在以下位置查找“auth.ts”：“./”、“./lib”、“./utils”或“./src”。 ## 核心配置选项选项 |注释 ---|--- `应用程序名称` |可选的显示名称 `baseURL` |仅当未设置“BETTER_AUTH_URL”时 `基本路径` |默认`/api/auth`。设置“/”为根。 `秘密` |仅当未设置“BETTER_AUTH_SECRET”时 `数据库` |除非使用无状态模式 (v1.4+)，否则是必需的 `辅助存储` | Redis/KV 用于会话和速率限制 `电子邮件和密码` | `{enabled: true }` 激活 `社会提供者` | `{ 谷歌: { clientId, clientSecret }, ... }` `插件` |插件数组 `trustedOrigins` | CSRF白名单 ## 插件参考插件 |描述 ---|--- 双因素| TOTP、电子邮件 OTP、备份代码组织|多租户组织、团队、邀请、RBAC 管理员 |用户管理、冒充、禁止密钥| WebAuthn无密码登录魔法链接 |基于电子邮件的无密码登录智威汤逊 |具有密钥轮换的 JWT 令牌，JWKS oauthProvider |构建您自己的 OAuth 2.1 提供程序（单独的 `@better-auth/oauth-provider` 包）单点登录 |具有 OIDC、OAuth2、SAML 2.0 的企业 SSO（单独的“@better-auth/sso”包）科学与技术 |企业用户配置（单独的“@better-auth/scim”包）条纹|付款和订阅管理持票人 |移动/CLI 的 API 令牌身份验证 api 密钥 |基于令牌的身份验证，具有速率限制一键 | Google One Tap 无摩擦登录匿名|无需 PII 的访客用户访问通用OAuth |使用 PKCE 的自定义 OAuth 提供程序电子邮件OTP |基于电子邮件的一次性密码验证电话号码 |基于电话/短信的 OTP 登录用户名 |基于用户名的登录（替代电子邮件）多会话 |同一浏览器中的多个帐户开放API |交互式 API 文档位于“/api/auth/reference” ## 会话策略战略|格式|使用案例 ---|---|--- 紧凑（默认）| Base64url + HMAC-SHA256 |最小、最快智威汤逊 |标准智威汤逊 |可互操作 JWE | A256CBC-HS512 加密 |最安全 ## 开始使用对于新项目或首次 Better Auth 设置，请使用官方交互式设置技巧： npx 技能添加 better-auth/skills -s create-auth-skill 这将逐步完成框架检测、数据库选择、身份验证方法选择、插件设置，并生成初始配置。 ## 反模式反模式|正确的做法 ---|--- 使用`d1Adapter` |将 Drizzle 或 Kysely 适配器与 `provider: "sqlite"` 一起使用在配置中使用表名 |使用 ORM 模型名称，而不是 DB 表名称插件更改后忘记 CLI |重新运行 `npx @better-auth/cli@latest generated` `tanstackStartCookies()` 不是最后一个插件 |必须是数组中的最后一个插件（TanStack Start）检查“会话”的登录状态 |检查“session?.user”——会话对象始终为真缺少 `nodejs_compat` 标志 | Cloudflare Workers 的“wrangler.toml”中需要带有身份验证的 Kysely CamelCasePlugin |使用单独的 Kysely 实例而不使用插件使用旧的“reactStartCookies”导入 |在 v1.4.14 中从“better-auth/tanstack-start”重命名为“tanstackStartCookies” ## 常见错误错误|正确的模式 ---|--- 当环境变量已设置时，在配置中设置 `baseURL` 和 `secret` |仅当未设置“BETTER_AUTH_URL”和“BETTER_AUTH_SECRET”环境变量时才在配置中定义这些使用 CommonJS require 语法与 better-auth v1.4+ | better-auth 自 v1.4.0 起仅限 ESM；专门使用“import”语法添加或更改插件后不重新运行 CLI 生成 |在插件更改后始终运行“npx @better-auth/cli@latestgenerate”以更新数据库架构检查“session”对象的真实状态以进行登录检测 |检查 `session?.user` 来代替；会话对象本身总是真实的直接将 `d1Adapter` 用于 Cloudflare D1 |使用 Drizzle 或 Kysely 适配器与 `provider: "sqlite"` 实现 D1 兼容性 ## 重大变更版本 |改变 ---|--- v1.4.14 | `reactStartCookies` 重命名为 `tanstackStartCookies` （从 `better-auth/tanstack-start` 导入） v1.4.6 | “allowImpersonatingAdmins”默认为“false” v1.4.0 |仅 ESM（无 CommonJS）； SSO、SCIM、OAuth 提供程序已移至单独的包中 v1.3.0 |多团队表结构：需要新的“teamMembers”表 ## 代表团在进行身份验证时，委托给： *“应用程序安全”——安全架构和威胁建模 * `database` — Drizzle ORM 模式和迁移 * `tanstack-start` — TanStack Start 集成模式 ## 资源 * **文档**： * **选项参考**： * **LLMs.txt** ： * **变更日志**： * **TanStack 开始**： * **博览会**： ## 参考文献 * [数据库适配器]() — Drizzle、Kysely、Prisma 适配器、Cloudflare Workers 工厂模式 * [会话管理]() — Cookie 缓存、无状态会话、存储优先级、freshAge 约束 * [插件和社交身份验证]() — 插件设置、OAuth 2.1 提供程序、管理 RBAC、社交提供程序范围 * [电子邮件和密码]() — 验证、密码重置、定时攻击预防、散列（scrypt、argon2）、令牌安全 * [双因素身份验证]() — TOTP、电子邮件/短信 OTP、备份代码、可信设备、2FA 会话流 * [组织]() — 多租户组织、团队、邀请、RBAC、动态访问控制、生命周期挂钩 * [配置]() — 用户/帐户配置、速率限制、挂钩、CSRF、可信来源、cookie/OAuth 安全性、生产清单 * [框架集成]() — TanStack Start 设置、Expo/React Native、客户端导入、类型安全 * [迁移指南]() — 使用架构映射和会话策略从 NextAuth/Auth.js、Clerk 或 Supabase Auth 迁移 * [故障排除]() — D1 一致性、CORS、OAuth 重定向、admin 403、nanostore 刷新、已知错误

更好的身份验证

包含技能