For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /zh/docs/tanstack/authentication.md (or send Accept: text/markdown).
身份认证
登录方式、会话与账户安全。
创建并验证真实账户
身份验证意味着证明谁在使用该应用程序。启动 Postgres 并首先使用数据库指南运行迁移，然后保持 Web 服务器运行。打开http://localhost:3000/auth,选择电子邮件/密码注册，输入您的姓名、电子邮件和密码，然后提交。保留 EMAIL_PROVIDER=local 进行第一次测试。
当流程请求电子邮件代码时，请在另一个浏览器选项卡中打开 http://localhost:3000/mail-preview，找到该地址的最新消息并将其代码复制回登录表单。如果代码过期，请请求新的代码。这些消息保留在本地发件箱中；反复检查外部收件箱将找不到它们。注销，然后再次登录以确认数据库支持的帐户正常工作。
如果注册报告数据库连接或缺少表错误，请完成数据库设置而不是启用社交登录。 Google、GitHub、Apple、X 和 Microsoft 按钮需要自己的提供商应用程序和回调设置；仅在其提供程序指南完成后才启用它。 Better Auth 是出厂默认引擎，不需要付费身份验证帐户即可进行本地电子邮件登录。
选择启用的登录方式
基础包含邮箱/密码、OTP 与可配置的社交认证。Better Auth 负责身份与会话，应用则组合供应商配置与 OTP 的事务性投递。
只启用你已配置的社交供应商。供应商客户端密钥与认证密钥留在服务端。
把身份连接到工作区
已认证的 handler 在访问工作区记录之前先解析会话状态。工作区开通必须保持幂等，使重放生命周期钩子不会创建重复的归属记录。
验证会话行为
测试登录、无效或过期 OTP、一次性消费、退出与匿名访问拒绝。内存适配器测试覆盖 handler 语义；生产数据库持久化与真实供应商回调需要单独验收。
安装与配置
Better Auth 是默认引擎(AUTH_PROVIDER=better-auth);Auth.js 引擎供以它为标准的团队使用。启用的方式按提供商声明:邮箱/密码、通过事务邮件投递的一次性代码,以及 Google、Apple、GitHub、Microsoft 和 Twitter 的社交登录。
每个社交提供商通过其 AUTH_<PROVIDER>_ENABLED 标志加上对应的 client id 和 secret 开启。认证密钥、提供商密钥和会话签名密钥是仅限服务器的配置。
AUTH_PROVIDER=better-auth
AUTH_SECRET=generate-a-long-random-value
AUTH_GOOGLE_ENABLED=true
GOOGLE_CLIENT_ID=…
GOOGLE_CLIENT_SECRET=…实现流程
/auth 界面渲染已配置的方式;服务器在 auth-runtime 中组装引擎,并在每个受保护边界解析会话。首次登录成功会以幂等方式为成员开通个人工作区 —— 重复的生命周期钩子绝不能创建第二条所有权记录。
账户安全位于 /settings/security:密码修改、活跃会话,以及在构建启用时的 passkey。将会话恢复、登出吊销和跨工作区拒绝保持为服务器强制的行为,而非界面状态。
验证与排障
验证登录、无效和过期的 OTP 代码、一次性消费、HTTPS 源上的 passkey 流程、社交回调返回、登出以及匿名拒绝。在测试回调前注册每个提供商的重定向 URI,并确认已吊销的会话无法继续执行受保护的操作。