用途:为当前 Convex + Web 应用接入 @convex-dev/auth,端到端完成登录鉴权,默认使用 Passkey,OAuth 或密码方式可选。
主要步骤:安装并固定 @convex-dev/auth,加入 convex.config.ts;在 convex/auth.ts 中添加提供方(默认 Passkey);无交互地生成鉴权密钥,不运行交互式 npx @convex-dev/auth wizard(它在无 TTY、匿名或 CI 环境会挂起),改用 jose 以可导出的 RS256 生成 JWT_PRIVATE_KEY 与 JWKS;随后设置 JWT_PRIVATE_KEY、JWKS 与 SITE_URL;编写 convex/auth.config.ts;接入客户端 ConvexAuthProvider、登录组件与路由守卫;完成后验证真实登录往返。
使用方式:使用 pnpm 时需额外安装 pnpm add jose。设置环境变量优先用 Convex MCP 的 envSet 工具逐条写入;CLI 回退时用 NAME=VALUE 形式,如 npx convex env set "JWT_PRIVATE_KEY=$JWT",不要写成 env set JWT_PRIVATE_KEY "$JWT"(值以 -----BEGIN 开头会被当作未知参数)。SITE_URL 填开发地址。密钥生成后删除 .auth-keys.json。如导入 shadcn/ui 组件,需先用 npx shadcn@latest add <name> 安装,否则构建失败。
限制:auth.config.ts 缺失或不正确会导致应用静默始终未登录且无报错;交互式向导在无头环境不可用。其他平台与收费信息暂未提供。