本技能是面向 Convex 后端的开发指南,围绕查询、变更、动作、HTTP 端点、文件存储、数据库 schema 与认证提供可操作的实现模式与示例代码。
适用场景:实现 Convex 后端功能;为表与索引设计数据库 schema;为 webhook 或外部 API 访问添加 HTTP 端点;实现异步动作与定时任务;配置认证与授权;排查 Convex 相关问题;处理文件存储与 URL。
核心模式
-
函数类型区分(关键):查询只读、不能修改数据库,用于获取数据,可被组件调用,具有缓存与响应式特性;变更用于写入数据库,包括创建、更新、删除,可调度动作,具有事务性;动作用于外部副作用,如调用第三方 API、发送邮件、与外部服务交互,不能直接访问数据库,必须通过查询或变更完成数据操作。规则是从变更中调度动作,绝不在变更中直接调用动作。示例中错误写法为在 mutation 的 handler 中直接 ctx.runAction,正确写法为 ctx.scheduler.runAfter(0, api.actions.sendEmail, args)。
-
HTTP 端点 CORS(关键):所有浏览器访问的 HTTP 端点必须包含 CORS 头,否则浏览器会拦截请求。资料给出 CORS_HEADERS 常量,包含 Access-Control-Allow-Origin、Access-Control-Allow-Methods、Access-Control-Allow-Headers、Vary 等字段,并要求在所有成功响应、错误响应与 OPTIONS 预检响应中携带。缺少时端点可能在 Postman 与 curl 中可用,但在浏览器应用中失败。
-
存储 URL 生成:始终使用 ctx.storage.getUrl() 获取存储 URL,不能手动拼接;手动构造的 URL 不可用并返回 null。
-
HTTP 端点域名(关键):HTTP 端点使用 .convex.site,而不是 .convex.cloud。资料示例中错误写法直接使用 NEXT_PUBLIC_CONVEX_URL 拼路径会导致 404,正确写法是把 .convex.cloud 替换为 .convex.site 后再拼接路径。.convex.cloud 用于 Convex 控制台。
关键文件:convex/schema.ts 定义数据库 schema,包括表、索引与关系;convex/http.ts 定义 HTTP 路由与处理器;convex/_generated/api.js 为自动生成的 API 类型,不可编辑;convex/auth.config.ts 为认证配置,资料示例使用 Clerk JWT。
认证模式:Convex 通过 JWT 与 Clerk 集成。在 HTTP action 中从 Authorization 头获取 token,去掉 Bearer 前缀;在查询或变更中通过 ctx.auth.getUserIdentity() 获取已认证用户,未认证时抛出 Unauthorized。
工作流 1:创建 HTTP 端点。步骤包括定义 CORS_HEADERS;使用 httpRouter 与 httpAction 创建路由,解析请求体、校验必填字段,调用变更或动作,成功与错误响应均携带 CORS 头;添加 OPTIONS 处理器;可选添加认证,校验 Authorization 头的 Bearer 前缀;前端使用 .convex.site 域名发起 fetch 请求。
工作流 2:设计数据库 schema。使用 defineSchema、defineTable 与 v 校验器定义表,为频繁查询字段添加单字段索引或复合索引;规则是查询哪个字段就为哪个字段添加索引;用 withIndex 在查询中使用索引;schema 变更通过 npx convex dev 或生产推送自动部署。
工作流 3:定时动作模式。适用于 API 调用、邮件、后台任务等异步操作。先创建 action 处理副作用,例如调用外部邮件 API 并可再通过 ctx.runMutation 更新数据库;再从 mutation 中调度该 action。定时选项包括 runAfter(0, ...) 立即异步执行、runAfter(60000, ...) 延迟一分钟、runAt(timestamp, ...) 在指定时间执行。
工作流 4:带进度的文件存储。先通过 mutation 调用 ctx.storage.generateUploadUrl() 生成上传 URL;前端用 fetch 上传文件并获得 storageId,再把 storageId 保存到数据库;读取文件 URL 时在查询中调用 ctx.storage.getUrl()。
常见排查:浏览器 CORS 被拦截,原因是响应缺少 CORS 头,需在所有响应与 OPTIONS 中加入;HTTP 端点 404,原因是使用了 .convex.cloud 域名,需替换为 .convex.site;存储 URL 返回 null,原因是手动拼接 URL,需改用 ctx.storage.getUrl();HTTP 端点 401,可能原因是缺少 Bearer 前缀、Clerk JWT 配置问题(检查控制台中的 CLERK_JWT_ISSUER_DOMAIN 与 auth.config.ts 的 issuer domain、JWT 模板)或 token 过期。
完成前检查清单:函数类型是否正确;HTTP 端点所有响应是否含 CORS 头;是否有 OPTIONS 预检处理;schema 是否为查询字段建立索引;异步操作是否使用调度动作;动作是否从变更中调度而非直接调用;前端是否使用 .convex.site 域名;存储 URL 是否使用 ctx.storage.getUrl();需要认证处是否校验;错误响应是否包含状态码与 CORS 头。
最佳实践:保持函数职责单一;严格使用 TypeScript 与生成类型;按查询需要建立索引但避免过度索引;优雅处理错误并返回正确状态码;先用 npx convex dev 本地测试再部署;保护敏感操作并校验认证;使用环境变量而非硬编码密钥。
参考资料指向 .claude/experts/convex-expert/expertise.yaml、.claude/agents/agent-convex.md 与官方文档 https://docs.convex.dev。技能未提供收费、价格、平台限制等其它信息。