用户认证与登录 是做什么的?
此应用在 /api/auth/* 路径下运行其自有的 Better Auth 服务,并通过 genericOAuth 插件连接到共享的 Grok 认证代理 (auth.grok.me)。该模板已预配好 Google 和 X 的登录渠道。
支持的登录方式——仅限以下三种,其他方式均不支持:Google、X 以及邮箱/密码。 不要添加其他社交/OAuth 提供商(如 GitHub、Apple、Discord 等),也不支持魔法链接、通行密钥、一次性密码、手机/SMS 或匿名登录。请勿向 GROK_PROVIDERS 添加任何条目。关于各登录方式的详细说明以及邮箱/密码开关(仅编辑 src/lib/auth/email-password.ts),请参见 references/sign-in-methods.md。
例外情况——看门人(gate viewer)用户已经登录,绝不要为他们渲染登录/重新认证按钮。对于连接器/应用数据类应用,仅显示“继续使用 Grok”按钮,不显示 Google/X 按钮,详见 references/grok-identity.md。
登录功能默认关闭——模板附带的 .grok/app-env.json 中设置为 {"VITE_AUTH_ENABLED": "false"},因此仅在需要用户账户时(参见 AGENTS.md §0.5)才开启此功能。开启过程请参考下方“开启登录功能”。
一旦开启,登录功能是真实的——包括在沙箱实时预览中也是如此。 请不要创建 demo/模拟/硬编码的用户。预览模式下:弹出窗口 + 内置预览客户端;部署后:每个应用有自己的客户端 + DATABASE_URL + 零点击看门人登录(详见 references/prewired-and-env.md)。
当功能关闭时(VITE_AUTH_ENABLED=false),会返回一个开发用户,以便非认证应用在未登录访客的情况下正常渲染——仅限开发环境和预览模式。部署后,该标志由平台控制(始终为 "true"),因此 requireUserId 会拒绝所有访客——关闭认证的应用不会使用它或 authMiddleware。
所有相关代码已预先安装并预配在 src/lib/auth/ 目录下——请勿执行 npm install 安装任何内容;better-auth 是唯一的认证包(绝不使用 @neondatabase/*、@stackframe/* 或 @clerk/*)。不要编辑或重写 src/lib/auth/ 下的任何文件——尤其是 server.ts——但 email-password.ts 中的标志配置除外。文件映射详见 references/prewired-and-env.md。
/auth/popup 路径已由模板的 Vite 插件处理(vite.config.ts → popup.server.ts):它不会渲染 React 应用。不要创建 src/routes/auth/popup.tsx(或任何位于该路径的 React 页面/客户端 OAuth 代码)——这会导致弹出窗口中显示完整应用,是常见的错误模式。
不要在此沙箱中编写 .env / .env.local / .env.example 文件:实时预览需要零环境配置,部署后的应用由平台注入其变量。可用的配置项在 references/prewired-and-env.md 中——绝不要向客户端暴露非 VITE_ 开头的变量。
migrations/auth/0001_auth.sql 是 Better Auth 的数据库模式——不要编辑。它位于 migrations/ 目录之外(不会被任何应用器递归处理),因此不会应用于没有登录功能的应用;“开启登录功能”时会将其复制到正确位置。
开启登录功能
请执行以下所有步骤——仅添加路由会使应用渲染登录功能被禁用的分支:
- 标志位: 从
.grok/app-env.json中删除VITE_AUTH_ENABLED键,然后重启开发服务器。Vite 在启动时读取环境变量,因此 HMR 不会感知到这一变化。npm run dev、npm run build和npm run preview都通过scripts/with-app-env.mjs读取该文件,因此预览和构建输出会同步切换——绝不要直接启动 Vite。 - 数据库模式: 执行
cp migrations/auth/0001_auth.sql migrations/0001_auth.sql,然后重启以使模式生效。该文件通过基本名称在_migrations表中跟踪,因此已应用过的数据库不会重复执行。 - 路由: 添加
src/routes/api/auth/$.ts和src/routes/login.tsx——从references/wiring.md复制这两个文件(通配 API 路由是使/api/auth/*和代理回调生效的关键)。 - 退出登录: 有登录没有退出是不完整的——渲染来自
@/lib/auth/gates的<UserButton />组件(它连接到signOut()函数;对看门人会话隐藏退出按钮)。 - 现有数据: 将应用的服务器函数包装在
authMiddleware中(关闭认证的应用之前不应使用该中间件——参见neon技能)。在启用登录之前已有的行是开发数据:除非用户另有要求,否则应删除并重新创建它们——不要将其交给第一个登录的用户。
开启后的进一步构建
- 登录/退出: 使用
@/lib/auth/client中的signIn(providerId)和signOut()函数;GROK_PROVIDERS负责渲染按钮。弹出窗口、Bearer Token 传递以及请求附加等内部机制请勿修改。优先使用<UserButton />(它会处理待处理和失败状态);signOut()在部署后如果服务器未确认会拒绝操作——请捕获该异常。不要使用authClient.signOut():它会使预览的 Bearer Token 附加到后续所有请求,导致访客始终处于登录状态。 - 读取用户信息:
useCurrentUser()仅用于显示(null表示“加载中”或“已注销”,因此不要单独依赖它进行重定向);应使用useCurrentUserState()的isPending属性进行守卫。守卫组件(SignedIn、SignedOut、SignInGate、RedirectToSignIn、UserButton)位于@/lib/auth/gates。关于 CTA 硬规则、骨架屏以及基于 Cookie 的 SSR 无闪烁方案,请参见references/session-ui.md。 - 用户专属数据(必需): 每个操作用户数据的服务端函数都必须使用预置的
authMiddleware,并且所有读和写操作都要作用域限制在context.userId中——Postgres 驱动程序拥有完整的数据库访问权限,因此没有其他限制能约束查询。请将user_id列保持为TEXT类型;绝不要信任客户端提供的用户 ID;若用户未登录,中间件会抛出UnauthorizedError(401 状态码)。相关代码和禁用模式下的语义请参见references/per-user-data.md。 - 安全模型: 无头代理、
__Host-Cookie +trustedOrigins以及 Fetch-Metadata 同源隔离均已预置——绝不要为了消除某个错误而削弱它们(references/sign-in-methods.md涵盖了模型和“无效来源”修复方法)。