Jerbix

登录与注册

开启认证模块，接入 Google 登录与邮箱验证

最近更新 2026 年 11 月 3 日

认证模块提供注册、登录、找回密码与邮箱验证。页面在 /{locale}/auth/*，API 在 /api/auth/*， 登录后的账号设置见个人中心。

登录页
登录页：邮箱密码登录，配置 Google 凭据后自动出现第三方登录按钮

步骤

  1. 打开认证模块。

``ts // src/config/website.ts auth: { enabled: true, requireEmailVerification: true }, ``

auth.enabled 同时门禁页面与 API：关闭时 /{locale}/auth/* 与 /api/auth/* 一起 404。

  1. 配好生产必填的两个变量。
变量要求说明
BETTER_AUTH_SECRET≥ 32 字符签名会话与邮件 token；生产缺失时 pnpm deploy 第一步就失败
BETTER_AUTH_URL完整 origin生成回调与邮件链接的绝对地址；部署工作流默认取 VITE_BASE_URL

BETTER_AUTH_SECRET 用 openssl rand -base64 32 生成，按部署到 Cloudflare 里的方式上传为运行时 secret。

  1. （可选）接入 Google 登录。 需要两个服务端变量，缺一不可：
变量说明
GOOGLE_CLIENT_IDGoogle Cloud Console 里 OAuth 客户端的 ID
GOOGLE_CLIENT_SECRET同一个客户端的 secret

两个都配齐，登录页才出现 Google 按钮；只配 ID 时按钮不显示，也不会留下一个必然失败的 入口。在 Google Cloud Console 的 OAuth 客户端里登记回调地址：

字段值
授权的 JavaScript 来源https://<your-domain>
授权的重定向 URIhttps://<your-domain>/api/auth/callback/google

本地开发另加 http://localhost:3000 与 http://localhost:3000/api/auth/callback/google。

  1. （可选）开启邮箱验证。 requireEmailVerification: true 要求新用户先验证邮箱才能登录，

它依赖邮件模块：按邮件配好 provider 与 MAIL_FROM 后，注册与登录才会真的发信。

验证

  • 本地 pnpm dev 后打开 /{locale}/auth/register 注册一个账号，应收到验证邮件。
  • 线上 curl -s https://<your-domain>/api/auth/get-session 返回 200 且 session 为 null，

说明认证 API 正常。

  • pnpm run check:env:prod 通过，说明生产变量与已启用模块的配置齐备。

注意事项

  • requireEmailVerification 是安全控制，不是邮件开关：它不随 mail.enabled 关闭而自动放开。

要求验证而邮件未配齐时，认证 API 返回 503，不会降级成免验证登录。

  • Google 登录不受邮箱验证拦截——Google 返回已验证的邮箱，只有邮箱密码路径受这条约束。
  • 密钥类环境变量一律不加 VITE_ 前缀，否则会打进客户端 bundle。