convex-setup-auth

Convex Authentication Setup 用于在 Convex 中实现安全的认证、用户管理与访问控制。

用途

首次为 Convex 应用设置认证。
实现用户管理（users 表、身份映射）。
创建认证辅助函数。
设置认证提供商：Convex Auth、Clerk、WorkOS AuthKit、Auth0、自定义 JWT。

不适用场景

非 Convex 后端的认证。
纯 OAuth/OIDC 文档，不涉及 Convex 实现。
与认证无关、只是碰巧出现在认证代码附近的调试问题。
认证提供商已完全配置好，只需一行修复的情况。

第一步：选择认证提供商 Convex 支持多种认证方式，不要默认某一提供商。在编写设置代码前：

除非仓库已明确表明，否则先询问用户想用哪种认证方案。
如果仓库已使用某提供商，除非用户想切换，否则沿用该提供商。
如果用户未选择且仓库未明确，先询问再继续。

常见选项：

Convex Auth：当用户希望由 Convex 直接处理认证时的良好默认选择。
Clerk：应用已使用 Clerk，或用户需要 Clerk 托管认证功能时使用。
WorkOS AuthKit：应用已使用 WorkOS，或用户明确需要 AuthKit 时使用。
Auth0：应用已使用 Auth0 时使用。
自定义 JWT 提供商：集成上述未覆盖的现有认证系统时使用。

询问前先查找仓库中的信号：

依赖：@clerk/、@workos-inc/、@auth0/* 或 Convex Auth 包。
现有文件：convex/auth.config.ts、认证中间件、提供商包装器或登录组件。
明确指向某提供商的环境变量。

选择提供商之后阅读该提供商的官方指南以及对应的本地参考文件：

Convex Auth：官方文档，然后 references/convex-auth.md
Clerk：官方文档，然后 references/clerk.md
WorkOS AuthKit：官方文档，然后 references/workos-authkit.md
Auth0：官方文档，然后 references/auth0.md

本地参考文件包含具体工作流、预期文件与环境变量、注意事项和验证检查。这些来源用于：包安装、客户端提供商接线、环境变量、convex/auth.config.ts 设置、登录与登出 UI 模式、React/Vite/Next.js 框架特定设置。

共享认证行为以 Convex 官方文档为准：

Auth in Functions：ctx.auth.getUserIdentity()
Storing Users in the Convex Database：可选的 app 级用户存储
Authentication：通用认证与授权指导
Convex Auth Authorization：提供商为 Convex Auth 时

优先使用官方文档而非凭记忆的步骤，因为提供商 CLI 与 Convex Auth 内部实现会随版本变化，凭记忆编造设置可能带来过时模式。对第三方提供商，仅当应用确实需要在 Convex 中存储用户文档时才添加 app 级用户存储，并非每个应用都需要 users 表。对 Convex Auth，遵循其文档和内置认证表，不要额外添加并行的 users 表加 storeUser 流程，因为 Convex Auth 已在内部管理用户记录。运行提供商初始化命令后，需检查生成文件并完成提供商参考中列出的初始化后接线步骤；初始化命令很少能完成整个集成。

核心模式：保护后端函数最常见的认证任务是在 Convex 函数中检查身份。

// Bad: trusting a client-provided userId
export const getMyProfile = query({
  args: { userId: v.id("users") },
  handler: async (ctx, args) => {
    return await ctx.db.get(args.userId);
  },
});

// Good: verifying identity server-side
export const getMyProfile = query({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    return await ctx.db
      .query("users")
      .withIndex("by_tokenIdentifier", (q) =>
        q.eq("tokenIdentifier", identity.tokenIdentifier),
      )
      .unique();
  },
});

工作流

确定提供商：询问用户或从仓库推断。
询问用户现在只做本地设置还是直接做生产就绪设置。
阅读匹配的提供商参考文件。
按官方提供商文档获取当前设置细节。
按官方 Convex 文档处理共享后端认证行为、用户存储与授权模式。
仅当文档与应用需求要求时才添加 app 级用户存储。
仅在应用需要时添加归属、角色或团队访问的授权检查。
如需，验证登录状态、受保护查询、环境变量与生产配置。

如果流程因提供商或部署的交互式设置而阻塞，明确向用户说明所需的人工步骤，待其完成后继续。对于面向 UI 的认证流程，可在设置完成后提出验证真实的注册或登录流程；若环境有浏览器自动化工具可使用，否则给用户一份简短的人工验证清单。

参考文件提供商参考：

references/convex-auth.md
references/clerk.md
references/workos-authkit.md
references/auth0.md

检查清单

编写设置代码前已选择正确的认证提供商
已阅读相关提供商参考文件
已询问用户要本地设置还是生产就绪设置
提供商特定接线使用官方提供商文档
共享认证行为与授权模式使用官方 Convex 文档
仅在应用确实需要时才添加 app 级用户存储
未为 Convex Auth 发明跨提供商的 users 表或 storeUser 流程
在受保护后端函数中添加认证检查
在应用确实需要处添加授权检查
错误消息清晰（“Not authenticated”、“Unauthorized”）
已为所选提供商配置客户端认证提供商
如被要求，生产认证设置也已覆盖

技能介绍