用途
Convex Backend 技能用于借助 Convex 构建类型安全的后端逻辑,并实现实时数据同步。它适合以下场景:构建实时协作应用(聊天、仪表盘、多人游戏);需要无需管理基础设施的后端;希望使用带自动缓存的类型安全服务端函数;构建需要响应式数据(智能体状态、流式结果)的 AI 应用;使用托管数据库加函数进行快速原型开发。
主要能力
该技能覆盖 Convex 的核心开发要素:
- Schema 定义:通过
defineSchema和defineTable定义数据表、字段类型与索引,例如用户表、消息表、频道表,并支持by_email、by_role、by_channel等索引。 - 查询(Queries):实时读取数据,支持索引查询、排序、限制数量,并可关联解析用户等关联数据。
- 变更(Mutations):写入数据,包含认证身份检查、查找或创建用户、插入记录等逻辑。
- 动作(Actions):调用外部 API(如 AI 接口),并通过
ctx.runMutation将结果写回数据库。 - 定时函数(Cron Jobs):使用
cronJobs配置按间隔或按 cron 表达式运行的任务,如清理旧消息、生成每日报告。 - 认证集成:通过
auth.config.ts配置认证提供方,并在 React 客户端使用ConvexProviderWithClerk等集成。 - React 客户端使用:使用
useQuery和useMutation实现实时自动更新与数据写入。 - 部署:使用
npx convex deploy部署到生产环境,支持环境变量文件、设置与查看环境变量、查看日志、手动运行函数。 - 文件存储:通过
ctx.storage.generateUploadUrl生成上传 URL,通过ctx.storage.getUrl获取文件 URL。
使用方式
前置条件:Node.js 18+、npm 或 pnpm、Convex 账号(免费额度:每月 100 万次函数调用)。
快速开始:
在已有项目中初始化:
npm install convex
npx convex dev # 启动本地开发(与云端同步)
在新项目中:
npm create convex@latest
部署到生产环境:
npx convex deploy
npx convex deploy --env-file .env.production
设置环境变量:
npx convex env set ANTHROPIC_API_KEY sk-ant-...
npx convex env list
查看日志与手动运行函数:
npx convex logs
npx convex logs --follow
npx convex run messages:listByChannel '{"channelId": "abc123"}'
适用场景
- 实时协作应用:聊天、仪表盘、多人游戏。
- 需要响应式数据的 AI 应用:智能体状态、流式结果。
- 希望零基础设施管理的后端开发。
- 需要类型安全服务端函数与自动缓存的场景。
- 使用托管数据库加函数进行快速原型开发。
最佳实践
- 在编写函数前先定义 schema 与校验。
- 尽可能保持变更幂等。
- 在每个特权查询/变更中检查认证身份。
- 为高读取集合尽早添加索引。
- 使用内部函数处理仅服务端逻辑(定时任务、webhook)。
- 将密钥存储在 Convex 环境变量中,绝不写入代码。
- 在 React 客户端使用乐观更新以获得即时 UI 反馈。
限制
- 基础设施命令可能中断服务:在变更状态前确认目标主机/范围,并准备备份或快照。
- 本技能为仅文档导入:上游脚本与模板未随附。
- 动作有 10 分钟超时限制,需拆分为更小步骤。
- 查询过慢时需添加匹配查询模式的数据库索引。
- 类型错误时运行
npx convex dev重新生成类型。 - 认证不工作时检查
auth.config.ts与提供方域名。 - 部署失败时检查
npx convex logs并确认环境变量已设置。
相关技能
- firebase-app-platform:替代的托管后端。
- vercel-deployments:前端托管。
- agent-observability:为 AI 驱动的后端流程添加可观测性。