Convex 接入 WorkOS AuthKit 完整实战指南：从 convex.json 配置到生产环境落地

• 数据库
• 后端

【免费下载链接】convex-backend

The open-source reactive database for app developers

项目地址：https://gitcode.com/gh_mirrors/co/convex-backend

点击查看免费下载

AuthKit 是 WorkOS 提供的托管式登录认证服务，本文以开源仓库 convex-backend 中convex-setup-auth技能的 workos-authkit.md 参考文档为主线，结合仓库内 CLI 源码与 waitlist 示例应用，系统讲解在 Convex 应用中接入 WorkOS AuthKit 的完整流程：包括 Convex-managed 与既有 WorkOS 团队两条接入路径、convex.json的authKit段配置、WorkOS 环境变量、convex/auth.config.ts的 JWT 校验、前端 Provider 与回调接线，以及生产环境与常见坑位。读完本文，你将具备从零到生产环境完整落地 Convex + WorkOS AuthKit 登录体系的能力。

一、为什么选择 WorkOS AuthKit，以及两条接入路径

1.1 适用场景

workos-authkit.md明确指出：当应用已经在使用 WorkOS，或者用户明确希望使用 AuthKit 时，才选择这条路。如果项目尚未选定认证方案，convex-setup-auth技能（SKILL.md）给出的候选还包括 Convex Auth、Clerk、Auth0 和自定义 JWT Provider——WorkOS AuthKit 只是其中的一个分支，不应默认选择。

在动手之前，技能要求先通过仓库信号判断是否已存在认证方案：

• 依赖中是否出现@workos-inc/*、@clerk/*、@auth0/*等 Provider 包；
• 是否已存在convex/auth.config.ts、认证中间件、Provider 包装组件或登录组件；
• 环境变量中是否已有指向某个 Provider 的明显痕迹。

若仓库已经存在 WorkOS 配置，应当保留现有租户模型（tenant model），除非用户明确要求变更。

1.2 两条接入路径：Convex-managed 还是既有 WorkOS 团队

这是整个接入流程的第一个分叉点，文档要求先确认用户想要哪种：

路径	适用场景	关键动作
Convex-managed WorkOS 团队	用户没有现成 WorkOS 组织，希望 Convex 代管	运行npx convex dev，走交互式引导流程，由 Convex 自动完成 AuthKit 环境开通与本地环境变量生成
既有 WorkOS 团队	用户已有 WorkOS 账号与组织	从 WorkOS Dashboard 获取WORKOS_CLIENT_ID与WORKOS_API_KEY，用npx convex env set写入 Convex 环境

从 CLI 源码看，workos.ts 中正是通过backend.get("WORKOS_CLIENT_ID")与backend.get("WORKOS_API_KEY")从 Convex 后端读取凭据，并在缺失时给出"手动设置WORKOS_CLIENT_ID和WORKOS_API_KEY"以及npx convex env set的明确提示——这与参考文档的既有团队路径完全对应。

二、整体工作流：先读文档、再确认、后动手

参考文档给出的 Workflow 是一个强顺序流程，核心原则是在写任何设置代码之前先阅读官方指南，因为 Provider 的 CLI 与 Convex Auth 内部实现会随版本变化，凭记忆编写设置代码极易使用过时模式。整体顺序如下：

1. 确认用户确实要 WorkOS AuthKit；
2. 确定要 Convex-managed 团队还是既有 WorkOS 团队；
3. 询问本次是仅本地（local-only）还是需要生产就绪（production-ready）配置；
4. 阅读官方 Convex 与 WorkOS AuthKit 指南；
5. 为应用的框架与实际本地端口创建或更新convex.json；
6. 根据上述选择走正确的设置分支；
7. 配置 WorkOS 所需环境变量；
8. 配置convex/auth.config.ts以校验 WorkOS 签发的 JWT；
9. 接线客户端 Provider 与回调流程；
10. 验证认证请求能到达 Convex；
11. 若需要生产就绪，覆盖生产 WorkOS 配置；
12. 仅在应用确实需要一级用户记录时，才添加storeUser或users表。

其中第 12 条值得特别强调：不是每个应用都需要users表。只有需要在 Convex 内部存储与用户身份绑定的业务数据（如用户资料、偏好设置）时，才应引入storeUser或users表。文档多次重复这一原则，可见这是最常见的过度设计点。

三、convex.json：AuthKit 配置的一等公民，而非可选项

参考文档反复强调：convex.json不是可选配置。它驱动着重定向 URI、首页 URL、CORS 配置以及本地环境变量生成，是托管式 AuthKit 流程的基石。

3.1 authKit 段的结构与字段

从 CLI 的配置解析源码 config.ts 可以看到authKit段的字段定义：

• redirectUris（string[]）：允许的回调重定向 URI 列表；
• appHomepageUrl（string）：应用首页 URL；
• corsOrigins（string[]）：允许的 CORS 来源列表；
• environmentType：仅允许出现在prod段（源码第 236 行附近的校验逻辑明确authKit.environmentType is only allowed in the prod section）；
• localEnvVars：仅支持 dev 部署（源码第 261 行附近说明 preview 与 prod 必须直接在部署平台上配置环境变量）。

配置解析逻辑（getAuthKitConfig）会优先读取显式的authKit配置；若convex.json中缺少该段，CLI 会提示"从最新模板复制convex.json或添加authKit段"（config.ts）。这从源码层面印证了文档"convex.json不是可选项"的论断。

一个典型的convex.json大致形态如下（字段名以仓库源码为准，具体值需按你的框架与实际端口填写）：

{ "authKit": { "dev": { "redirectUris": ["http://localhost:5173/auth/callback"], "appHomepageUrl": "http://localhost:5173", "corsOrigins": ["http://localhost:5173"] }, "prod": { "environmentType": "production", "redirectUris": ["https://your-app.example.com/auth/callback"], "appHomepageUrl": "https://your-app.example.com", "corsOrigins": ["https://your-app.example.com"] } } }

注意：当前仓库中 waitlist 示例应用的 convex.json 仅包含$schema与aiFiles配置，尚未启用 AuthKit——它正好可以作为一个"接入前"的基线状态参考。接入 AuthKit 时需按上述结构补充authKit段。

3.2 端口不一致是最隐蔽的坑

文档的 Gotchas 部分给出了两个关联性极强的提醒：

• Vite 默认端口 5173 可能被占用：如果其他应用正在运行，Vite 会回退到其它端口。不能假设默认端口仍然匹配生成的 AuthKit 配置。
• 前端实际端口与 convex.json 不一致的后果：托管式 WorkOS 登录流程会指向错误的回调 URL。此时需要更新convex.json、更新本地重定向环境变量，并重新运行npx convex dev。

3.3 托管式团队：convex dev 的交互式引导

对于 Convex-managed 团队，运行npx convex dev即可走交互式引导流程。CLI 会：

• 自动开通/配置 AuthKit 环境；
• 为 Vite 应用把VITE_WORKOS_CLIENT_ID、VITE_WORKOS_REDIRECT_URI等本地环境变量写入.env.local。

关键提醒：convex dev的首次运行是交互式的。如果在非交互式终端中执行，应当停下来请用户亲自完成引导提示，而不能跳过。这也是技能文档强调"交互流程受阻时明确询问用户所需的人工步骤"的原因。

四、WorkOS 环境变量清单

参考文档列出的 WorkOS 相关环境变量分为后端与前端两类：

环境变量	归属	说明
WORKOS_CLIENT_ID	Convex 后端	WorkOS 客户端 ID，Convex 端 JWT 校验与托管流程必需
WORKOS_API_KEY	Convex 后端	WorkOS API 密钥，用于服务端调用 WorkOS API
WORKOS_COOKIE_PASSWORD	后端（框架相关）	用于加密 AuthKit 会话 Cookie 的密码（至少 32 字节）
VITE_WORKOS_CLIENT_ID	Vite 前端	前端向 WorkOS 发起登录用的公开客户端 ID
VITE_WORKOS_REDIRECT_URI	Vite 前端	前端登录成功后的回调地址
NEXT_PUBLIC_WORKOS_REDIRECT_URI	Next.js 前端	Next.js 应用的公开回调地址

在既有 WorkOS 团队路径下，从 WorkOS Dashboard 获取WORKOS_CLIENT_ID与WORKOS_API_KEY后，通过npx convex env set写入 Convex 部署环境。CLI 源码 workos.ts 中给出了明确的命令形态：

npx convex env set WORKOS_CLIENT_ID $YOUR_CLIENT_ID_HERE npx convex env set WORKOS_API_KEY $YOUR_API_KEY_HERE

源码还展示了构建环境变量时的优先级逻辑：读取部署环境变量，其次回退到process.env.WORKOS_CLIENT_ID（workos.ts），并会在凭据不一致时提示用npx convex env remove清理后重新设置（workos.ts）。

核心纪律：绝不混用 dev 与 prod 的 WorkOS 凭据或重定向 URI；文档明确要求 dev 与 prod 需要不同的客户端 ID / API Key 时，务必分开维护。

五、convex/auth.config.ts：让 Convex 信任 WorkOS 签发的 JWT

convex/auth.config.ts是 Convex 侧认证的"信任锚点"。它的作用是把 WorkOS 这个 OAuth/OIDC Provider 声明为 Convex 认可的 JWT 签发方，之后 Convex 才能校验 WorkOS 签发的令牌，并在后端函数中通过ctx.auth.getUserIdentity()暴露用户身份。

接入 AuthKit 时，该文件需要：

• 声明 WorkOS 作为 JWT Provider，配置其 issuer（签发方域）与相关的客户端标识；
• 保证与convex.json中authKit段、以及 WorkOS Dashboard 中的客户端配置三者一致。

修改convex/auth.config.ts之后，必须运行常规的npx convex dev或部署流程，让后端同步新配置——这一点在参考文档与技能文档（SKILL.md 的 Gotchas 部分）中都被反复强调。若 Convex 报"no auth provider matched the token"，首先要核查的就是convex/auth.config.ts与 WorkOS 端的配置是否匹配。

六、前端接线：Provider、Callback 与 Token 流入

6.1 客户端 Provider 与回调

前端部分的核心工作有三块：

1. 安装与框架匹配的 WorkOS SDK（React、Vite、Next.js 等框架包不同）；
2. 包装客户端 Provider：在应用根部接入 WorkOS 的认证 Provider，把登录状态与令牌管理交给它；
3. 回调/重定向路由：登录成功后 WorkOS 会重定向回应用，回调路由需要正确落地（Next.js 等需要显式路由的地方尤其如此），并把拿到的令牌流转给 Convex。

6.2 认证后的后端防护模式

接入登录后，后端函数必须"服务端验证身份"，而不是信任客户端传入的 userId。技能文档 SKILL.md 给出了一个正反对比示例，这个模式对 WorkOS AuthKit 同样适用：

// 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(); }, });

正确模式通过ctx.auth.getUserIdentity()从 Convex 侧验证令牌，再基于identity.tokenIdentifier查询用户记录。错误信息应当清晰明确（如"Not authenticated"、"Unauthorized"），而不是含糊的通用异常。

6.3 验证的终点是"Convex 看到认证状态"

文档的 Validation 部分给出了明确的验证终点：

• 用户能完成登录流程并回到应用；
• 回调 URL 与实际前端端口一致（本地开发）；
• 登录成功后 Convex 能收到认证请求，即前端不再停留在"托管式 WorkOS 页面加载成功"这一步——文档特别警告：不要以"托管式 WorkOS 页面打开了"作为完成标志。

七、逐步落地：两条路径的 Concrete Steps

参考文档的 Concrete Steps 可以归纳为如下可执行清单，两条路径仅在环境变量来源上分叉：

1. 选择 Convex-managed 或既有 WorkOS 团队；
2. 为应用框架创建或更新convex.json的authKit段；
3. 确保 dev 的redirectUris、appHomepageUrl、corsOrigins以及本地重定向环境变量与应用真实本地端口一致；
4. Convex-managed：运行npx convex dev并走完交互式引导（自动生成本地环境变量）；
5. 既有团队：从 WorkOS Dashboard 获取WORKOS_CLIENT_ID与WORKOS_API_KEY，用npx convex env set设置；
6. 创建或更新convex/auth.config.ts，配置 WorkOS JWT 校验；
7. 运行常规npx convex dev或部署流程，让后端配置同步生效；
8. 在应用中接线 WorkOS 客户端 Provider；
9. 配置回调与重定向处理；
10. 验证用户能登录并回到应用；
11. 验证 Convex 在登录后能看到已认证用户；
12. 若需要生产就绪，同步配置生产客户端 ID、API Key、重定向 URI 与部署设置。

八、生产环境配置：从 dev-only 到 production-ready

文档将"仅本地"与"生产就绪"视为需要主动询问的分叉，而不是默认行为。生产就绪意味着：

• 配置生产 WorkOS 客户端 ID、API Key、重定向 URI；
• 配置 Convex 生产部署（preview/prod）的convex.jsonauthKit段，包括environmentType字段；
• 生产环境变量直接在部署平台上配置，而不是依赖convex dev生成的本地.env.local（这一点与源码中"localEnvVars仅支持 dev"的校验逻辑一致）；
• 在宣布任务完成前，逐项验证生产的重定向与回调设置。

此外文档有一条流程纪律：默认不要把笔记文件静默写入仓库。只有用户明确需要上线/交接文档时，才显式创建。

九、Gotchas 汇总：最容易翻车的 8 个点

综合参考文档与技能文档，以下是 WorkOS AuthKit 接入中最常见的坑：

1. 路径分叉不清：官方文档将 Convex-managed 与既有团队分开描述，不明显时应先问清用户走哪条路；
2. dev/prod 配置混淆：不同客户端 ID 或 API Key 时保持隔离，不混用凭据与重定向 URI；
3. 过度建模：只有应用真正需要一级用户行时才加storeUser或users表；
4. 已有 WorkOS 配置被破坏：仓库已有 WorkOS 设置时保留现有租户模型，除非用户要求变更；
5. 非交互终端的托管引导：convex dev首次运行是交互式的，非交互终端下应停下来请用户完成提示；
6. 忽略 convex.json：托管流程下它是必需配置，驱动重定向、首页 URL、CORS 与本地环境变量生成；
7. 端口漂移：Vite 可能因端口被占而回退到非 5173 端口，不能假设默认端口仍匹配生成的配置；发现不对就更新convex.json、更新本地重定向环境变量并重新npx convex dev；
8. 验证停在半路：成功的 WorkOS 登录应重定向回本地回调路由并到达 Convex 认证状态，而不是停在"托管页面加载完成"。

十、接入完成 Checklist

参考文档的最终 Checklist 可作为落地验收标准：

• 确认用户需要 WorkOS AuthKit
• 询问是仅本地还是生产就绪
• 选定 Convex-managed 或既有 WorkOS 团队
• 创建或更新convex.json（含authKit段）
• 配置 WorkOS 环境变量
• 配置convex/auth.config.ts
• 登录后验证认证请求能到达 Convex（ctx.auth.getUserIdentity()非空）
• 若需要，配置生产部署

延伸阅读

• 技能主文档：convex-setup-auth/SKILL.md：Provider 选择流程、后端防护代码模式与整体工作流；
• 同目录其他 Provider 参考：clerk.md、auth0.md、convex-auth.md：用于对比不同认证方案；
• CLI 配置解析源码：config.ts：authKit段的字段与校验规则；
• WorkOS 集成实现：workos.ts：环境变量读写、npx convex env set流程与托管式引导实现；
• 示例应用：waitlist：接入 AuthKit 前的 Vite + Convex 应用基线，其convex.json、package.json与src/App.tsx可作为改造起点。

赞分享

• 数据库
• 后端

【免费下载链接】convex-backend

The open-source reactive database for app developers

项目地址：https://gitcode.com/gh_mirrors/co/convex-backend

点击查看免费下载

相关推荐

• Convex 集成 WorkOS AuthKit 完整实战指南：从 `convex.json` 自动配置到 JWT 校验与生产部署

  Convex 集成 WorkOS AuthKit 完整实战指南：从 convex.json 自动配置到 JWT 校验与生产部署 导读 本文基于 convex b

  数据库后端

• 在 Convex 中集成 WorkOS AuthKit：从 convex.json 自动配置到 JWT 校验的完整实战指南

  在 Convex 中集成 WorkOS AuthKit：从 convex.json 自动配置到 JWT 校验的完整实战指南 WorkOS AuthKit 是 C

  数据库后端

• Convex Auth：在 Convex 后端直接落地的完整认证接入指南（convex-backend 仓库实战）

  Convex Auth：在 Convex 后端直接落地的完整认证接入指南（convex backend 仓库实战） Convex Auth 是 Convex 官

  数据库后端