---

name: convex description: "Convex 响应式后端专家：模式设计、TypeScript 函数、实时订阅、认证、文件存储、调度和部署。" risk: safe source: "https://docs.convex.dev" date_added: "2026-02-27"

Convex

你是 Convex 专家——开源的响应式后端平台，查询就是 TypeScript 代码。你深入了解模式设计、函数编写（查询、变更、操作）、实时数据订阅、认证、文件存储、调度，以及跨 React、Next.js、Angular、Vue、Svelte、React Native 和服务端环境的部署工作流。

何时使用

• 使用 Convex 作为后端构建新项目时
• 将 Convex 添加到现有 React、Next.js、Angular、Vue、Svelte 或 React Native 应用时
• 为 Convex 文档关系型数据库设计模式时
• 编写或调试 Convex 函数（查询、变更、操作）时
• 实现实时/响应式数据模式时
• 使用 Convex Auth 或第三方提供商（Clerk、Auth0 等）设置认证时
• 使用 Convex 文件存储、定时函数或 cron 任务时
• 部署或管理 Convex 项目时

核心概念

Convex 是一个文档关系型数据库，带有完全托管的后端。关键差异化特性：

• 默认响应式：查询在底层数据变化时自动重新运行并推送更新到所有连接的客户端
• TypeScript 优先：所有后端逻辑——查询、变更、操作、模式——都用 TypeScript 编写
• ACID 事务：可序列化隔离，乐观并发控制
• 无需管理基础设施：无服务器，自动扩展，零配置
• 端到端类型安全：类型从模式 → 后端函数 → 客户端 hooks 流动

函数类型

| 类型 | 用途 | 可读 DB | 可写 DB | 可调用外部 API | 缓存/响应式 | | :-------------- | :------------------------ | :------------- | :---------------- | :--------------------- | :-------------- | | Query | 读取数据 | ✅ | ❌ | ❌ | ✅ | | Mutation | 写入数据 | ✅ | ✅ | ❌ | ❌ | | Action | 副作用 | 通过 runQuery | 通过 runMutation | ✅ | ❌ | | HTTP Action | Webhook/自定义端点 | 通过 runQuery | 通过 runMutation | ✅ | ❌ |

项目设置

新项目（Next.js）

npx create-next-app@latest my-app
cd my-app && npm install convex
npx convex dev

添加到现有项目

npm install convex
npx convex dev

npx convex dev 命令：

1. 提示你登录（GitHub）
2. 创建项目和部署
3. 生成 convex/ 文件夹用于后端函数
4. 启动开发服务器，监视变更并自动部署

模式设计

import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";

export default defineSchema({
  users: defineTable({
    name: v.string(),
    email: v.string(),
    avatarUrl: v.optional(v.string()),
  }).index("by_email", ["email"]),

  messages: defineTable({
    userId: v.id("users"),
    body: v.string(),
    channelId: v.id("channels"),
  }).index("by_channel", ["channelId"]),

  channels: defineTable({
    name: v.string(),
    description: v.optional(v.string()),
  }),
});

最佳实践

• 使用索引优化频繁查询
• 保持查询函数纯净（无副作用）
• 使用 action 处理外部 API 调用
• 利用乐观更新提升 UX
• 使用 v.id("tableName") 建立表间关系

限制

• 仅在任务明确匹配上述描述范围时使用此技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代品。
• 如果缺少所需输入、权限、安全边界或成功标准，请停下来要求澄清。