Convex

Convex：实时后端即平台的深度解析

NOTE

本文档最后更新于 2026年4月，深入剖析 Convex 的响应式查询、实时数据同步、认证系统、权限控制，以及在 AI 应用中的独特优势。

---

目录

1. 概述与核心优势
2. 快速开始与项目初始化
3. Schema 定义详解
4. Query 查询系统
5. Mutation 变更系统
6. Action 外部集成
7. 实时订阅与 Live Queries
8. 认证与权限
9. 文件存储
10. Convex 部署与扩展
11. 与其他方案对比
12. 实战场景
13. 选型建议

---

概述与核心优势

什么是 Convex

在现代 Web 应用开发中，实时数据同步已经成为许多应用的核心需求。从协作文档编辑、实时聊天、在线白板到多人游戏，这些场景都离不开数据的实时更新能力。传统的数据获取方式依赖于轮询或手动刷新，这种方式不仅效率低下，还会导致用户体验的下降——用户必须等待页面刷新或者手动点击刷新按钮才能看到最新数据。Convex 的出现正是为了解决这一痛点，它提供了一种全新的响应式数据编程范式，让开发者能够像操作本地状态一样操作远程数据。

Convex 是一个后端即平台（Backend as a Platform）服务，提供了一个完整的服务器端解决方案：数据库、实时订阅、认证、文件存储和 Serverless 函数，全部通过响应式 API 暴露给前端。与传统的 BaaS（如 Firebase、Supabase）不同，Convex 的核心创新是响应式查询。当数据库中的数据发生变化时，所有订阅了该数据的客户端会自动收到更新，无需轮询或手动刷新。这种编程范式的转变，就好像是从手动刷新电视频道变成了有线电视的实时传输——用户始终看到的是最新内容。

Convex 的设计哲学可以概括为三个核心原则：首先是极简的开发体验，开发者不需要关心网络请求、缓存管理、数据同步等底层细节，只需要声明需要什么数据，Convex 会自动处理一切；其次是强大的类型安全，从数据库 Schema 到前端代码，类型信息贯穿整个开发流程，编译时就能发现大部分错误；第三是真正的实时性，基于 WebSocket 的实时推送机制确保数据的即时同步，用户体验与本地应用无异。

从技术架构的角度来看，Convex 采用了一种独特的设计思路。它将后端函数分为三种类型：Query（查询）用于读取数据，支持实时订阅；Mutation（变更）用于修改数据，保证 ACID 事务；Action（动作）用于执行外部 API 调用等副作用操作。这种分类方式非常直观，让开发者能够清晰地组织后端逻辑。同时，Convex 使用 TypeScript 作为唯一的开发语言，从 Schema 定义到业务逻辑代码，全部使用 TypeScript，实现真正的端到端类型安全。

Convex 的技术定位

在当前的 BaaS 市场中，Convex 占据了一个独特的生态位。它不像 Firebase 那样采用 NoSQL 数据库，而是选择了 PostgreSQL 作为底层存储，这使得它天然支持复杂的关系查询和事务处理。同时，它的响应式模型比 Supabase 的实时订阅更加现代化——不需要手动管理订阅生命周期，Hooks 会自动处理订阅的创建和销毁。

对于 AI 应用开发来说，Convex 提供了几个独特的优势。第一，它能够原生存储和同步 AI 生成的流式数据，开发者可以轻松实现打字机效果的聊天界面。第二，它的乐观更新机制非常适合 AI 应用的场景——当用户发送消息时，界面可以立即显示“正在思考”的状态，然后在 AI 回复时平滑更新。第三，它的 Action 功能可以方便地集成各种 AI API，包括 OpenAI、Anthropic、Google AI 等主流服务。

核心特性详解

Convex 的核心特性可以从数据层、网络层、应用层三个维度来理解。在数据层，Convex 提供了一个类型安全的关系型数据库，支持 PostgreSQL 的所有主流特性，包括事务、索引、约束等。同时，它的 Schema 定义采用 TypeScript 代码而非 DSL，这种方式对于 TypeScript 开发者来说更加直观自然。在网络层，Convex 使用 WebSocket 实现客户端与服务端的实时双向通信，所有数据变更都会自动推送到订阅的客户端。在应用层，Convex 提供了完善的 React 集成，useQuery 和 useMutation 两个 Hook 几乎可以替代 Redux、React Query 等状态管理库。

特性	说明
响应式数据库	数据变更自动推送到订阅的客户端
实时订阅	WebSocket 驱动的 Live Queries
类型安全	自动生成的 TypeScript 类型
ACID 事务	强一致性的事务支持
无服务器函数	Action 用于外部 API 调用
内置认证	开箱即用的用户系统
文件存储	内置文件上传和 CDN
增量计算	自动缓存和优化

技术架构

┌─────────────────────────────────────────────────────────────────┐
│                        Convex 架构                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    Convex Cloud                         │    │
│  │                                                         │    │
│  │   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │    │
│  │   │  Database   │  │   Actions   │  │   Auth      │    │    │
│  │   │  (持久层)    │  │  (外部集成)  │  │  (认证)     │    │    │
│  │   └──────┬──────┘  └──────┬──────┘  └──────┬──────┘    │    │
│  │          │                 │                 │           │    │
│  │          └────────────┬────┴─────────────────┘           │    │
│  │                       │                                   │    │
│  │              ┌────────▼────────┐                          │    │
│  │              │  Subscription   │                          │    │
│  │              │    Engine        │                          │    │
│  │              └────────┬────────┘                          │    │
│  └───────────────────────┼───────────────────────────────────┘    │
│                          │                                       │
│            WebSocket 连接 │                                       │
│                          ▼                                       │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                      客户端                              │    │
│  │                                                         │    │
│  │   ┌─────────────────────────────────────────────────┐   │    │
│  │   │              useQuery() Hook                     │   │    │
│  │   │  自动订阅，自动更新，响应式数据                   │   │    │
│  │   └─────────────────────────────────────────────────┘   │    │
│  └─────────────────────────────────────────────────────────┘    │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

这个架构图清晰展示了 Convex 的工作原理。客户端通过 WebSocket 与 Convex Cloud 保持长连接，当数据库中的数据发生变化时，Subscription Engine 会自动检测变更并推送到所有订阅的客户端。在客户端，useQuery Hook 封装了订阅逻辑，开发者只需要声明需要的数据，Hook 会自动处理订阅的创建、更新和销毁。

Convex vs 其他方案

维度	Convex	Firebase	Supabase	tRPC + Prisma
实时数据	✅ 原生支持	✅	✅	❌ 需额外配置
响应式	✅ 自动推送	✅	❌ 需订阅	❌
数据库	SQL (PostgreSQL)	NoSQL	PostgreSQL	自选
类型安全	✅ 自动生成	部分	需手动	✅ 端到端
认证	内置	内置	内置/自定义	需集成
学习曲线	低	中	中	中高
供应商锁定	中	高	低	无
定价	按使用量	按使用量	按使用量	自托管免费

这个对比表帮助我们理解 Convex 在市场中的位置。Convex 的最大优势在于其响应式模型——与其他方案需要手动管理订阅或轮询不同，Convex 的数据会自动同步。这种“声明式的数据获取”方式极大地简化了前端代码，也让实时应用的开发变得前所未有的简单。

---

快速开始与项目初始化

安装与配置

开始使用 Convex 非常简单，只需要几个命令就能搭建起完整的后端服务。首先，你需要在本地安装 Convex CLI 并创建一个新项目。Convex 支持与 Next.js、Nuxt、Remix 等主流框架集成，同时也支持原生 React 和 Vue 项目。无论你使用哪种框架，Convex 的核心概念和使用方式都是一致的。

# 创建新项目
npm create convex@latest my-app
 
# 进入目录
cd my-app
 
# 安装依赖
npm install
 
# 登录 Convex
npx convex dev
 
# 在另一个终端启动开发服务器
npm run dev

npm create convex@latest 命令会引导你完成项目初始化，包括选择框架、配置数据库等步骤。如果你已经有了一个现有项目，也可以手动添加 Convex，过程也非常简单——只需要安装相关依赖并创建 Schema 文件即可。

项目结构

my-app/
├── convex/                  # Convex 后端代码
│   ├── convex.json         # Convex 配置
│   ├── schema.ts           # 数据库 Schema
│   ├── auth.ts             # 认证配置
│   ├── functions/          # Serverless 函数
│   │   ├── messages.ts     # 消息相关函数
│   │   └── users.ts        # 用户相关函数
│   └── storage.ts          # 文件存储配置
│
├── src/                    # 前端代码
│   ├── lib/
│   │   └── convex.ts       # Convex 客户端配置
│   └── ...
│
└── convex.config.ts        # 部署配置

这个项目结构展示了 Convex 的典型组织方式。convex/ 目录包含所有后端代码，包括数据库 Schema 定义、认证配置和各种 Serverless 函数。src/ 目录包含前端代码，其中 lib/convex.ts 是 Convex 客户端的配置入口。这种前后端分离的目录结构保持了代码的清晰组织，同时通过自动生成的文件确保类型安全。

基本配置

// convex.config.ts
import { defineApp } from 'convex/server';
 
export default defineApp({
  // 认证配置
  auth: {
    // 使用 Convex Auth 或自定义
  },
  
  // 存储配置
  storage: {
    // 文件大小限制（字节）
    maxFileSize: 10 * 1024 * 1024, // 10MB
    // 允许的文件类型
    allowedFileTypes: ['image/*', 'application/pdf'],
  },
  
  // 函数超时配置
  functions: {
    // 默认超时时间（毫秒）
    timeoutMs: 30000,
    // 最大超时时间
    maxTimeoutMs: 300000,
  },
});

配置文件允许你自定义 Convex 的各种行为，包括存储限制、函数超时时间等。这些配置在开发和生产环境可能有不同的值，通常通过环境变量来实现差异化配置。

---

Schema 定义详解

基础 Schema

Schema 是 Convex 应用的基石，它定义了数据库中的表结构、字段类型和索引。Convex 的 Schema 采用 TypeScript 代码编写，这使得它与现有的 TypeScript 项目完美融合。与 Prisma 的 DSL 或 TypeORM 的装饰器不同，Convex 的 Schema 定义更加直观，类似于定义一个普通的 TypeScript 对象。

// convex/schema.ts
import { defineSchema, defineTable } from 'convex/server';
import { v } from 'convex/values';
 
export default defineSchema({
  // 用户表（Convex Auth 自动管理）
  users: defineTable({
    name: v.string(),
    email: v.string(),
    image: v.optional(v.string()),
  }).index('by_email', ['email']),
 
  // 帖子表
  posts: defineTable({
    author: v.id('users'),
    title: v.string(),
    body: v.string(),
    published: v.boolean(),
    likes: v.number(),
    createdAt: v.number(),
    updatedAt: v.number(),
  })
    .index('by_author', ['author'])
    .index('by_published', ['published'])
    .index('by_created', ['createdAt']),
 
  // 评论表
  comments: defineTable({
    post: v.id('posts'),
    author: v.id('users'),
    body: v.string(),
    createdAt: v.number(),
  })
    .index('by_post', ['post'])
    .index('by_author', ['author']),
 
  // 点赞表（多对多关系）
  likes: defineTable({
    post: v.id('posts'),
    user: v.id('users'),
    createdAt: v.number(),
  })
    .index('by_post', ['post'])
    .index('by_user', ['user'])
    .index('by_post_user', ['post', 'user']),
});

这个示例展示了如何定义表、字段和索引。defineTable 创建一个新表，v.* 用于定义字段类型，index 方法用于创建查询索引。索引是优化查询性能的关键，合理设计索引可以显著提升查询效率。

字段类型详解

Convex 提供了丰富的字段类型，从基础的标量类型到复杂的嵌套类型应有尽有。理解这些类型的用法对于设计良好的数据库 Schema 至关重要。

import { v } from 'convex/values';
 
// 基础类型
v.string()           // 字符串
v.number()           // 数字
v.boolean()          // 布尔值
v.null()              // null
v.bytes()            // 二进制数据
 
// 复杂类型
v.id('tableName')    // 引用其他表的 ID
v.array(v.string())  // 数组
v.object({           // 对象
  name: v.string(),
  age: v.number(),
})
v.optional(v.string())  // 可选值
v.union(              // 联合类型
  v.object({ type: v.literal('a'), a: v.string() }),
  v.object({ type: v.literal('b'), b: v.number() }),
)
 
// 验证类型
v.literal('pending')  // 字面量
v.enum(['red', 'green', 'blue'])  // 枚举
 
// 时间类型（存储为数字时间戳）
v.datetime()          // 日期时间
v.date()              // 日期
 
// 地理类型
v.geography()         // 地理位置
 
// JSON 类型
v.any()               // 任意 JSON
v.record(v.string(), v.number())  // 记录/映射

这些类型覆盖了大多数应用场景。值得注意的是，v.id() 用于建立表之间的引用关系，这是关系型数据库建模的基础。v.optional() 表示可选字段，v.union() 则用于处理多态数据。

索引设计

索引是数据库性能优化的核心。在 Convex 中，索引通过 index 方法定义在表上。设计良好的索引可以加速查询，避免全表扫描。

// 单一字段索引
defineTable({
  email: v.string(),
}).index('by_email', ['email'])
 
// 多字段复合索引
defineTable({
  tenant: v.id('tenants'),
  status: v.string(),
  createdAt: v.number(),
})
  .index('by_tenant_status', ['tenant', 'status'])
  .index('by_tenant_created', ['tenant', 'createdAt'])
 
// 唯一约束
defineTable({
  slug: v.string(),
}).index('by_slug', ['slug'])
 
// 索引类型
.index('by_field', ['field'], { unique: true })  // 唯一索引
.index('by_field', ['field'], { sort: true })    // 排序优化索引

索引设计需要考虑查询模式。如果经常需要按某个字段过滤，就应该在那个字段上创建索引。如果需要同时按多个字段过滤，复合索引可能更合适。唯一索引确保字段值的唯一性，常用于 email、slug 等不允许重复的字段。

---

Query 查询系统

基础查询

Query 是 Convex 中用于读取数据的函数。它们本质上是 Serverless 函数，但专门用于数据查询。与普通 API 不同，Query 支持实时订阅——当底层数据发生变化时，所有订阅了该 Query 的客户端都会自动收到更新。

// convex/functions/posts.ts
import { query } from '../_generated/server';
import { v } from 'convex/values';
 
// 公开查询 - 获取所有已发布的帖子
export const list = query({
  args: {
    limit: v.optional(v.number()),
    cursor: v.optional(v.number()),
  },
  handler: async (ctx, args) => {
    const limit = args.limit ?? 10;
    
    let posts = await ctx.db
      .query('posts')
      .withIndex('by_published', (q) => q.eq('published', true))
      .order('desc')
      .take(limit + 1);
    
    const hasMore = posts.length > limit;
    if (hasMore) {
      posts = posts.slice(0, -1);
    }
    
    return {
      posts,
      nextCursor: hasMore ? posts[posts.length - 1].createdAt : null,
    };
  },
});
 
// 获取单个帖子
export const get = query({
  args: { postId: v.id('posts') },
  handler: async (ctx, args) => {
    const post = await ctx.db.get(args.postId);
    
    if (!post) {
      return null;
    }
    
    // 获取作者信息
    const author = await ctx.db.get(post.author);
    
    return {
      ...post,
      author: author ? { name: author.name, image: author.image } : null,
    };
  },
});
 
// 获取用户的帖子
export const byUser = query({
  args: { userId: v.id('users') },
  handler: async (ctx, args) => {
    const posts = await ctx.db
      .query('posts')
      .withIndex('by_author', (q) => q.eq('author', args.userId))
      .order('desc')
      .collect();
    
    return posts;
  },
});

Query 函数的结构非常清晰：args 定义输入参数，handler 是实际的数据获取逻辑。在 handler 中，ctx.db 是数据库操作的入口，ctx.db.query() 用于构建查询，withIndex 使用之前定义的索引来加速查询。

复杂查询

在实际应用中，查询往往更加复杂，可能需要分页、过滤、聚合等操作。Convex 的 Query API 支持这些高级用法。

// 分页查询
export const paginated = query({
  args: {
    cursor: v.optional(v.number()),
    limit: v.optional(v.number()),
    filter: v.optional(v.object({
      author: v.optional(v.id('users')),
      published: v.optional(v.boolean()),
    })),
  },
  handler: async (ctx, args) => {
    const limit = args.limit ?? 20;
    
    let q = ctx.db.query('posts').withIndex('by_created');
    
    // 应用游标
    if (args.cursor !== undefined) {
      q = q.filter((q) => q.lt(q.field('createdAt'), args.cursor!));
    }
    
    // 应用过滤器
    if (args.filter?.author) {
      q = q.filter((q) => q.eq(q.field('author'), args.filter!.author!));
    }
    if (args.filter?.published !== undefined) {
      q = q.filter((q) => q.eq(q.field('published'), args.filter!.published!));
    }
    
    const posts = await q.take(limit + 1);
    const hasMore = posts.length > limit;
    const items = hasMore ? posts.slice(0, -1) : posts;
    
    return {
      posts: items,
      nextCursor: hasMore ? items[items.length - 1].createdAt : null,
    };
  },
});
 
// 聚合查询
export const stats = query({
  args: { userId: v.id('users') },
  handler: async (ctx, args) => {
    const posts = await ctx.db
      .query('posts')
      .withIndex('by_author', (q) => q.eq('author', args.userId))
      .collect();
    
    const totalLikes = posts.reduce((sum, p) => sum + p.likes, 0);
    const publishedPosts = posts.filter((p) => p.published);
    
    return {
      totalPosts: posts.length,
      publishedPosts: publishedPosts.length,
      draftPosts: posts.length - publishedPosts.length,
      totalLikes,
      avgLikes: posts.length > 0 ? totalLikes / posts.length : 0,
    };
  },
});

分页是列表查询的常见需求。Convex 使用游标分页而非偏移量分页，这种方式在大数据量场景下更加高效——无论用户翻到第几页，查询性能都是稳定的。聚合查询则展示了如何在 Query 中进行简单的数据统计。

关联查询

现代应用很少只查询单个表的数据，更多时候需要获取关联的数据。Convex 支持在 Query 中进行关联查询。

// 获取帖子及其评论
export const withComments = query({
  args: { postId: v.id('posts') },
  handler: async (ctx, args) => {
    const post = await ctx.db.get(args.postId);
    
    if (!post) {
      return null;
    }
    
    const author = await ctx.db.get(post.author);
    const comments = await ctx.db
      .query('comments')
      .withIndex('by_post', (q) => q.eq('post', args.postId))
      .order('asc')
      .collect();
    
    // 获取评论者信息
    const commentsWithAuthors = await Promise.all(
      comments.map(async (comment) => {
        const author = await ctx.db.get(comment.author);
        return {
          ...comment,
          author: author ? { name: author.name, image: author.image } : null,
        };
      })
    );
    
    return {
      ...post,
      author: author ? { name: author.name, image: author.image } : null,
      comments: commentsWithAuthors,
    };
  },
});

关联查询的关键在于正确处理异步依赖。如果需要获取关联数据，应该在循环中使用 Promise.all 并行获取，而不是串行等待每个请求完成。

---

Mutation 变更系统

基础 Mutation

Mutation 是 Convex 中用于修改数据的函数。与 Query 一样，Mutation 也是 Serverless 函数，但它们可以修改数据库状态。每个 Mutation 都在一个事务中执行，确保数据的强一致性。

// convex/functions/posts.ts
import { mutation } from '../_generated/server';
import { v } from 'convex/values';
 
// 创建帖子
export const create = mutation({
  args: {
    title: v.string(),
    body: v.string(),
    published: v.boolean(),
  },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    
    if (!identity) {
      throw new Error('Not authenticated');
    }
    
    const user = await ctx.db
      .query('users')
      .withIndex('by_email', (q) => q.eq('email', identity.email!))
      .first();
    
    if (!user) {
      throw new Error('User not found');
    }
    
    const postId = await ctx.db.insert('posts', {
      author: user._id,
      title: args.title,
      body: args.body,
      published: args.published,
      likes: 0,
      createdAt: Date.now(),
      updatedAt: Date.now(),
    });
    
    return postId;
  },
});
 
// 更新帖子
export const update = mutation({
  args: {
    postId: v.id('posts'),
    title: v.optional(v.string()),
    body: v.optional(v.string()),
    published: v.optional(v.boolean()),
  },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    
    if (!identity) {
      throw new Error('Not authenticated');
    }
    
    const post = await ctx.db.get(args.postId);
    
    if (!post) {
      throw new Error('Post not found');
    }
    
    // 验证所有者
    const user = await ctx.db
      .query('users')
      .withIndex('by_email', (q) => q.eq('email', identity.email!))
      .first();
    
    if (!user || post.author !== user._id) {
      throw new Error('Not authorized');
    }
    
    const updates: Record<string, unknown> = { updatedAt: Date.now() };
    if (args.title !== undefined) updates.title = args.title;
    if (args.body !== undefined) updates.body = args.body;
    if (args.published !== undefined) updates.published = args.published;
    
    await ctx.db.patch(args.postId, updates);
    
    return { success: true };
  },
});
 
// 删除帖子
export const remove = mutation({
  args: { postId: v.id('posts') },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    
    if (!identity) {
      throw new Error('Not authenticated');
    }
    
    const post = await ctx.db.get(args.postId);
    
    if (!post) {
      throw new Error('Post not found');
    }
    
    const user = await ctx.db
      .query('users')
      .withIndex('by_email', (q) => q.eq('email', identity.email!))
      .first();
    
    if (!user || post.author !== user._id) {
      throw new Error('Not authorized');
    }
    
    // 删除相关评论
    const comments = await ctx.db
      .query('comments')
      .withIndex('by_post', (q) => q.eq('post', args.postId))
      .collect();
    
    for (const comment of comments) {
      await ctx.db.delete(comment._id);
    }
    
    // 删除帖子
    await ctx.db.delete(args.postId);
    
    return { success: true };
  },
});

Mutation 的结构与 Query 类似，但增加了数据修改操作。ctx.db.insert 用于插入新记录，ctx.db.patch 用于部分更新，ctx.db.delete 用于删除记录。在执行这些操作之前，务必要进行权限检查，确保用户有权执行相应操作。

点赞 Mutation

点赞是一个典型的需要原子操作的场景——需要同时更新点赞表和帖子的点赞计数。

// 点赞/取消点赞
export const toggleLike = mutation({
  args: { postId: v.id('posts') },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    
    if (!identity) {
      throw new Error('Not authenticated');
    }
    
    const user = await ctx.db
      .query('users')
      .withIndex('by_email', (q) => q.eq('email', identity.email!))
      .first();
    
    if (!user) {
      throw new Error('User not found');
    }
    
    // 检查是否已点赞
    const existingLike = await ctx.db
      .query('likes')
      .withIndex('by_post_user', (q) => 
        q.eq('post', args.postId).eq('user', user._id)
      )
      .first();
    
    const post = await ctx.db.get(args.postId);
    
    if (!post) {
      throw new Error('Post not found');
    }
    
    if (existingLike) {
      // 取消点赞
      await ctx.db.delete(existingLike._id);
      await ctx.db.patch(args.postId, {
        likes: Math.max(0, post.likes - 1),
      });
      return { liked: false, likes: post.likes - 1 };
    } else {
      // 添加点赞
      await ctx.db.insert('likes', {
        post: args.postId,
        user: user._id,
        createdAt: Date.now(),
      });
      await ctx.db.patch(args.postId, {
        likes: post.likes + 1,
      });
      return { liked: true, likes: post.likes + 1 };
    }
  },
});

这个例子展示了 Convex Mutation 的原子性保证。整个点赞切换逻辑在一个事务中执行，要么全部成功，要么全部失败。如果两个用户同时点赞或取消点赞，数据库状态始终保持一致。

评论 Mutation

评论功能需要处理嵌套回复、回复通知等复杂逻辑。

// 添加评论
export const addComment = mutation({
  args: {
    postId: v.id('posts'),
    body: v.string(),
  },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    
    if (!identity) {
      throw new Error('Not authenticated');
    }
    
    const user = await ctx.db
      .query('users')
      .withIndex('by_email', (q) => q.eq('email', identity.email!))
      .first();
    
    if (!user) {
      throw new Error('User not found');
    }
    
    const post = await ctx.db.get(args.postId);
    
    if (!post) {
      throw new Error('Post not found');
    }
    
    const commentId = await ctx.db.insert('comments', {
      post: args.postId,
      author: user._id,
      body: args.body,
      createdAt: Date.now(),
    });
    
    return commentId;
  },
});
 
// 删除评论
export const deleteComment = mutation({
  args: { commentId: v.id('comments') },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    
    if (!identity) {
      throw new Error('Not authenticated');
    }
    
    const comment = await ctx.db.get(args.commentId);
    
    if (!comment) {
      throw new Error('Comment not found');
    }
    
    const user = await ctx.db
      .query('users')
      .withIndex('by_email', (q) => q.eq('email', identity.email!))
      .first();
    
    if (!user || comment.author !== user._id) {
      throw new Error('Not authorized');
    }
    
    await ctx.db.delete(args.commentId);
    
    return { success: true };
  },
});

评论的权限检查确保只有评论作者才能删除自己的评论。父级评论的删除策略（是否同时删除子评论）取决于业务需求，通常通过 Schema 中的级联删除配置来处理。

---

Action 外部集成

Action 概述

Action 是 Convex 中用于执行副作用的函数。与 Query 和 Mutation 不同，Action 主要用于调用外部 API、发送邮件、处理支付等操作。它们在服务端执行，可以访问环境变量和外部服务。

// convex/functions/integrations.ts
import { action } from '../_generated/server';
import { v } from 'convex/values';

Action 的特点是它们不参与数据同步——它们执行的操作不会触发客户端的自动更新。如果需要在 Action 后更新数据，通常需要配合 Mutation 使用。

Stripe 支付集成

支付集成是 Action 的典型应用场景。Stripe API 不能在前端直接调用，需要通过服务端 Action 来处理。

// 支付集成
export const createCheckoutSession = action({
  args: {
    priceId: v.string(),
    successUrl: v.string(),
    cancelUrl: v.string(),
  },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    
    if (!identity) {
      throw new Error('Not authenticated');
    }
    
    const session = await stripe.checkout.sessions.create({
      mode: 'subscription',
      payment_method_types: ['card'],
      line_items: [
        {
          price: args.priceId,
          quantity: 1,
        },
      ],
      success_url: args.successUrl,
      cancel_url: args.cancelUrl,
      customer_email: identity.email!,
      metadata: {
        userId: identity.subject,
      },
    });
    
    return { sessionUrl: session.url };
  },
});

这个 Action 创建了一个 Stripe Checkout Session，并返回重定向 URL。前端只需要跳转到这个 URL 即可完成支付流程。

邮件发送

邮件发送是另一个常见的 Action 场景。SendGrid、Resend、Postmark 等邮件服务都可以通过 Action 集成。

// 发送邮件
export const sendEmail = action({
  args: {
    to: v.string(),
    subject: v.string(),
    html: v.string(),
  },
  handler: async (ctx, args) => {
    // 使用 Resend、SendGrid 或其他邮件服务
    const response = await fetch('https://api.resend.com/emails', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.RESEND_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        from: 'onboarding@resend.dev',
        to: args.to,
        subject: args.subject,
        html: args.html,
      }),
    });
    
    if (!response.ok) {
      throw new Error('Failed to send email');
    }
    
    return { success: true };
  },
});

邮件发送应该异步处理，避免阻塞用户请求。Convex 的调度器可以帮助实现后台发送。

AI 服务集成

在 AI 应用中，集成 OpenAI、Anthropic 等 AI 服务是最常见的 Action 用例。

// AI 补全
export const generateCompletion = action({
  args: {
    prompt: v.string(),
    maxTokens: v.optional(v.number()),
  },
  handler: async (ctx, args) => {
    const response = await fetch('https://api.openai.com/v1/chat/completions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'gpt-4o',
        messages: [
          { role: 'system', content: 'You are a helpful assistant.' },
          { role: 'user', content: args.prompt },
        ],
        max_tokens: args.maxTokens ?? 500,
      }),
    });
    
    if (!response.ok) {
      throw new Error('AI request failed');
    }
    
    const data = await response.json();
    return { completion: data.choices[0].message.content };
  },
});

将 AI 调用放在 Action 中有几个好处：首先，API 密钥可以安全地存储在服务端；其次，可以实现请求重试、超时处理等逻辑；第三，可以添加缓存层避免重复调用。

---

实时订阅与 Live Queries

前端订阅

Convex 的响应式模型在前端通过 React Hooks 实现。useQuery 是最核心的 Hook，它会自动订阅指定 Query 返回的数据。

// src/lib/convex.ts
import { ConvexReactClient } from 'convex/react';
 
const convexUrl = process.env.NEXT_PUBLIC_CONVEX_URL || '';
 
export const convex = new ConvexReactClient(convexUrl);

// src/components/PostList.tsx
'use client';
 
import { useQuery } from 'convex/react';
import { api } from '../convex/generated/api';
 
export function PostList() {
  // 自动订阅 posts 数据
  const postsData = useQuery(api.posts.list, { limit: 10 });
  
  if (postsData === undefined) {
    return <div>Loading...</div>;
  }
  
  return (
    <div>
      {postsData.posts.map((post) => (
        <PostCard key={post._id} post={post} />
      ))}
    </div>
  );
}

useQuery 的第一个参数是 Query 函数，第二个参数是传递给 Query 的参数。当数据库中的数据发生变化时，组件会自动重新渲染，无需手动刷新页面。undefined 的检查非常重要——它表示数据正在加载中，在数据加载完成之前不应该渲染内容。

Optimistic Updates

乐观更新是提升用户体验的重要技术。当用户执行某个操作时，界面立即显示预期的结果，然后异步发送到服务端。如果服务端返回错误，再回滚到之前的状态。

// 带乐观更新的点赞
export function LikeButton({ postId, initialLikes, isLiked }: Props) {
  const [optimisticLikes, setOptimisticLikes] = useState(initialLikes);
  const [optimisticLiked, setOptimisticLiked] = useState(isLiked);
  
  const toggleLike = useMutation(api.posts.toggleLike);
  
  const handleClick = async () => {
    // 乐观更新
    setOptimisticLiked(!optimisticLiked);
    setOptimisticLikes(optimisticLiked ? optimisticLikes - 1 : optimisticLikes + 1);
    
    try {
      await toggleLike({ postId });
    } catch (error) {
      // 回滚
      setOptimisticLiked(isLiked);
      setOptimisticLikes(initialLikes);
    }
  };
  
  return (
    <button onClick={handleClick}>
      {optimisticLiked ? '❤️' : '🤍'} {optimisticLikes}
    </button>
  );
}

乐观更新让应用感觉更加响应迅速，但需要注意错误处理。当服务端操作失败时，必须回滚到之前的状态，否则用户界面将与实际数据不一致。

订阅多个数据源

在复杂的页面中，可能需要同时订阅多个数据源。Convex 支持这种场景。

// src/components/Dashboard.tsx
'use client';
 
import { useQuery } from 'convex/react';
import { api } from '../convex/generated/api';
 
export function Dashboard() {
  // 并行订阅多个查询
  const [userPosts, stats, notifications] = [
    useQuery(api.posts.byUser, { userId: 'current-user-id' }),
    useQuery(api.posts.stats, { userId: 'current-user-id' }),
    useQuery(api.notifications.list),
  ];
  
  // 当任何一个还在加载时显示加载状态
  if (userPosts === undefined || stats === undefined || notifications === undefined) {
    return <DashboardSkeleton />;
  }
  
  return (
    <div>
      <StatsCard stats={stats} />
      <PostsList posts={userPosts} />
      <NotificationList notifications={notifications} />
    </div>
  );
}

多个 useQuery 调用会并行执行，数据加载完成后同时渲染。这种模式非常适合仪表盘类型的页面——每个数据块独立加载和更新。

---

认证与权限

Convex Auth 配置

Convex 提供了内置的认证解决方案 Convex Auth。它支持密码登录、社交登录、Magic Link 等多种认证方式，配置简单，开箱即用。

// convex/auth.ts
import { convexAuth } from '@convex-dev/auth';
import { Password } from '@convex-dev/auth/providers/Password';
import { query } from './_generated/server';
 
export const { auth, signIn, signOut, store } = convexAuth({
  providers: [
    Password({
      // 验证邮箱格式
      validateEmail(email) {
        return email.includes('@') ? email : null;
      },
      // 验证密码强度
      async validatePassword(password) {
        if (password.length < 8) {
          return 'Password must be at least 8 characters';
        }
        return null;
      },
    }),
  ],
  // 回调函数
  callbacks: {
    // 用户创建后
    async afterCreateNewUser(ctx, { userId, account }) {
      // 获取认证信息
      const identity = await ctx.auth.getUserIdentity();
      
      // 在 users 表中创建用户记录
      await ctx.db.insert('users', {
        name: identity?.givenName || identity?.name || '',
        email: identity?.email || '',
        image: identity?.picture || '',
      });
    },
  },
});
 
// 获取当前用户
export const currentUser = query({
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    
    if (!identity) {
      return null;
    }
    
    const user = await ctx.db
      .query('users')
      .withIndex('by_email', (q) => q.eq('email', identity.email!))
      .first();
    
    return user;
  },
});

认证配置中的 afterCreateNewUser 回调是连接认证系统和业务数据的桥梁。当新用户注册时，这个回调会被触发，你可以在此处创建用户的业务数据记录。

权限控制

权限控制是应用安全的关键。Convex 在 Query 和 Mutation 中都需要进行权限检查。

// convex/functions/posts.ts
 
// 私有查询 - 只有作者可以看到草稿
export const myDrafts = query({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    
    if (!identity) {
      throw new Error('Not authenticated');
    }
    
    const user = await ctx.db
      .query('users')
      .withIndex('by_email', (q) => q.eq('email', identity.email!))
      .first();
    
    if (!user) {
      throw new Error('User not found');
    }
    
    const posts = await ctx.db
      .query('posts')
      .withIndex('by_author', (q) => q.eq('author', user._id))
      .filter((q) => q.eq(q.field('published'), false))
      .collect();
    
    return posts;
  },
});
 
// 管理员查询
export const allPosts = query({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    
    if (!identity) {
      throw new Error('Not authenticated');
    }
    
    const user = await ctx.db
      .query('users')
      .withIndex('by_email', (q) => q.eq('email', identity.email!))
      .first();
    
    if (!user || user.role !== 'admin') {
      throw new Error('Admin access required');
    }
    
    return ctx.db.query('posts').collect();
  },
});

权限检查应该在函数的开头执行，确保未授权用户无法访问敏感数据。对于不同角色的用户，应该返回不同的数据或抛出不同的错误。

---

文件存储

文件上传

Convex 提供了内置的文件存储功能，支持图片、视频、文档等各种文件类型。

// convex/storage.ts
import { action } from '../_generated/server';
import { v } from 'convex/values';
 
// 生成上传 URL
export const generateUploadUrl = action({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    
    if (!identity) {
      throw new Error('Not authenticated');
    }
    
    return await ctx.storage.generateUploadUrl();
  },
});

文件上传采用预签名 URL 的方式：前端先请求服务端获取上传 URL，然后直接上传文件到 Convex 的存储服务。这种方式避免了大文件经过服务端造成的性能问题。

前端上传组件

// src/components/FileUpload.tsx
'use client';
 
import { useState } from 'react';
import { useAction, useMutation } from 'convex/react';
import { api } from '../convex/generated/api';
 
export function FileUpload() {
  const [file, setFile] = useState<File | null>(null);
  const [uploading, setUploading] = useState(false);
  
  const generateUploadUrl = useAction(api.storage.generateUploadUrl);
  const saveFile = useMutation(api.storage.saveFile);
  
  const handleUpload = async () => {
    if (!file) return;
    
    setUploading(true);
    
    try {
      // 1. 获取上传 URL
      const uploadUrl = await generateUploadUrl();
      
      // 2. 上传到 Convex
      const response = await fetch(uploadUrl, {
        method: 'POST',
        headers: { 'Content-Type': file.type },
        body: file,
      });
      
      if (!response.ok) {
        throw new Error('Upload failed');
      }
      
      const { storageId } = await response.json();
      
      // 3. 保存文件引用
      await saveFile({
        storageId,
        fileName: file.name,
        mimeType: file.type,
      });
      
      setFile(null);
      alert('File uploaded successfully!');
    } catch (error) {
      console.error('Upload error:', error);
      alert('Upload failed');
    } finally {
      setUploading(false);
    }
  };
  
  return (
    <div>
      <input
        type="file"
        onChange={(e) => setFile(e.target.files?.[0] || null)}
      />
      <button onClick={handleUpload} disabled={!file || uploading}>
        {uploading ? 'Uploading...' : 'Upload'}
      </button>
    </div>
  );
}

文件上传的三步流程清晰明了：获取上传 URL、执行上传、保存文件引用到数据库。这种分离的设计让上传逻辑更加灵活，可以添加验证、压缩、裁剪等预处理步骤。

---

Convex 部署与扩展

部署配置

Convex 支持云端托管和自托管两种部署方式。云端托管无需管理服务器，零配置部署。

// convex.config.ts
import { defineApp } from 'convex/server';
import auth from './auth';
 
export default defineApp({
  // 认证
  auth,
  
  // 存储限制
  storage: {
    maxFileSize: 50 * 1024 * 1024, // 50MB
  },
  
  // 区域配置
  regions: ['us-east-1', 'eu-west-1', 'ap-south-1'],
  
  // 监控
  telemetry: {
    enabled: true,
    provider: 'datadog',
    apiKey: process.env.DD_API_KEY,
  },
});

部署命令

# 开发
npx convex dev
 
# 部署到生产
npx convex deploy
 
# 查看部署状态
npx convex status
 
# 监控日志
npx convex logs --tail
 
# 回滚
npx convex rollback --deployment production

Convex 的部署流程非常简单。开发环境下，npx convex dev 会启动本地 Convex 服务器，同时监听文件变化自动重新加载。生产部署只需要 npx convex deploy 一个命令即可完成。

---

与其他方案对比

Convex vs Supabase

维度	Convex	Supabase
实时订阅	✅ WebSocket 原生	✅ PostgreSQL 订阅
响应式	✅ 自动推送	❌ 需手动订阅
数据库	PostgreSQL	PostgreSQL
类型安全	✅ 自动生成	需 Prisma/Drizzle
认证	内置 Auth	内置/自定义
文件存储	✅ 内置	✅ Storage
定价	按使用量	按使用量

Convex 和 Supabase 都使用 PostgreSQL 作为底层数据库，但编程模型完全不同。Supabase 沿用了传统的请求-响应模型，而 Convex 则带来了响应式的数据更新。

Convex vs Firebase

维度	Convex	Firebase
数据库类型	SQL	NoSQL
实时数据	✅	✅
响应式	✅	❌
类型安全	✅ 自动	部分
定价模型	按使用量	按操作量
供应商锁定	中	高

Firebase 的 NoSQL 数据库在大规模数据场景下有优势，但缺乏类型安全。Convex 的 SQL 数据库更适合需要复杂查询的应用。

---

实战场景

场景一：实时聊天应用

聊天应用是 Convex 的典型应用场景之一。消息的实时同步、已读状态、在线状态等功能都可以轻松实现。

// convex/functions/chat.ts
 
// 发送消息
export const sendMessage = mutation({
  args: {
    conversationId: v.id('conversations'),
    content: v.string(),
  },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    
    if (!identity) {
      throw new Error('Not authenticated');
    }
    
    const user = await ctx.db
      .query('users')
      .withIndex('by_email', (q) => q.eq('email', identity.email!))
      .first();
    
    if (!user) {
      throw new Error('User not found');
    }
    
    const messageId = await ctx.db.insert('messages', {
      conversationId: args.conversationId,
      senderId: user._id,
      content: args.content,
      createdAt: Date.now(),
    });
    
    // 更新会话的最后消息
    await ctx.db.patch(args.conversationId, {
      lastMessage: args.content,
      lastMessageAt: Date.now(),
    });
    
    return messageId;
  },
});

前端订阅消息查询后，新消息会自动显示，无需手动刷新页面。

---

选型建议

选择 Convex 的理由

• ✅ 需要实时数据同步
• ✅ 想要响应式更新（无需手动刷新）
• ✅ 快速原型开发
• ✅ 不想管理服务器
• ✅ 需要内置认证
• ✅ TypeScript 项目

不选择 Convex 的场景

• ❌ 想要完全自托管
• ❌ 需要 NoSQL 数据库
• ❌ 项目预算极其有限
• ❌ 需要高级查询功能（如全文搜索）
• ❌ 团队偏好 SQL 迁移工具

---

参考资料

资源	链接
官方文档	https://docs.convex.dev
Convex Auth	https://auth.convex.dev
GitHub	https://github.com/get-convex/convex
示例项目	https://docs.convex.dev/examples
Discord	https://discord.gg/convex

---

SUCCESS

Convex 是构建实时应用的绝佳选择，其响应式查询和实时数据同步能力让复杂应用的开发变得简单。对于需要多人协作、实时更新的 vibecoding 项目，Convex 提供了开箱即用的完整解决方案。

---

Convex 高级模式与最佳实践

后台任务与定时任务

// convex/scheduler.ts
import { internalMutation, internalQuery } from './_generated/server';
 
// 定时清理过期数据
export const cleanupExpiredSessions = internalMutation({
  args: {},
  handler: async (ctx) => {
    const now = Date.now();
    const oneMonthAgo = now - 30 * 24 * 60 * 60 * 1000;
 
    // 获取过期会话
    const expiredSessions = await ctx.db
      .query('sessions')
      .filter((q) => q.lt(q.field('expiresAt'), oneMonthAgo))
      .collect();
 
    // 删除过期会话
    for (const session of expiredSessions) {
      await ctx.db.delete(session._id);
    }
 
    return { deleted: expiredSessions.length };
  },
});

乐观锁与冲突处理

// convex/functions/tasks.ts
export const updateTask = mutation({
  args: {
    taskId: v.id('tasks'),
    title: v.optional(v.string()),
    completed: v.optional(v.boolean()),
    version: v.number(), // 用于乐观锁
  },
  handler: async (ctx, args) => {
    const task = await ctx.db.get(args.taskId);
 
    if (!task) {
      throw new Error('Task not found');
    }
 
    // 乐观锁检查版本
    if (task.version !== args.version) {
      throw new Error('Conflict: Task was modified by another user');
    }
 
    const updates: Record<string, unknown> = {
      updatedAt: Date.now(),
      version: task.version + 1,
    };
 
    if (args.title !== undefined) updates.title = args.title;
    if (args.completed !== undefined) updates.completed = args.completed;
 
    await ctx.db.patch(args.taskId, updates);
 
    return { success: true, newVersion: task.version + 1 };
  },
});

乐观锁通过版本号检测并发修改。当两个用户同时修改同一数据时，后提交的用户会遇到冲突错误，需要重新获取最新数据后重试。

多租户隔离

// convex/schema.ts
export const organizations = defineTable({
  name: v.string(),
  slug: v.string(),
  plan: v.union(
    v.literal('free'),
    v.literal('pro'),
    v.literal('enterprise')
  ),
  createdAt: v.number(),
}).index('by_slug', ['slug']);
 
export const tenants = defineTable({
  organization: v.id('organizations'),
  name: v.string(),
  settings: v.object({
    theme: v.optional(v.string()),
    features: v.optional(v.array(v.string())),
  }),
  createdAt: v.number(),
}).index('by_organization', ['organization']);
 
// 权限检查
export const canAccessTenant = query({
  args: { tenantId: v.id('tenants') },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) return false;
 
    const user = await ctx.db
      .query('users')
      .withIndex('by_email', (q) => q.eq('email', identity.email!))
      .first();
 
    if (!user) return false;
 
    const tenant = await ctx.db.get(args.tenantId);
    if (!tenant) return false;
 
    // 检查用户是否是租户成员
    const membership = await ctx.db
      .query('tenant_members')
      .withIndex('by_user_tenant', (q) =>
        q.eq('user', user._id).eq('tenant', args.tenantId)
      )
      .first();
 
    return !!membership;
  },
});

多租户隔离是 SaaS 应用的核心需求。每个查询都应该检查用户是否有权访问当前租户的数据，防止数据泄露。

---

Convex 与 AI 应用

AI 生成内容

// convex/functions/ai.ts
import { action } from '../_generated/server';
import { v } from 'convex/values';
 
export const generatePost = action({
  args: {
    topic: v.string(),
    style: v.optional(v.union(
      v.literal('informative'),
      v.literal('casual'),
      v.literal('technical')
    )),
  },
  handler: async (ctx, args) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error('Not authenticated');
 
    // 调用 OpenAI
    const response = await fetch('https://api.openai.com/v1/chat/completions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'gpt-4o',
        messages: [
          {
            role: 'system',
            content: `You are a blog post writer. Write ${args.style ?? 'informative'} content.`
          },
          {
            role: 'user',
            content: `Write a blog post about: ${args.topic}`
          }
        ],
        max_tokens: 2000,
      }),
    });
 
    const data = await response.json();
    const content = data.choices[0].message.content;
 
    // 生成 slug
    const slug = args.topic
      .toLowerCase()
      .replace(/[^a-z0-9]+/g, '-')
      .replace(/^-|-$/g, '');
 
    // 获取用户
    const user = await ctx.db
      .query('users')
      .withIndex('by_email', (q) => q.eq('email', identity.email!))
      .first();
 
    if (!user) throw new Error('User not found');
 
    // 创建帖子
    const postId = await ctx.db.insert('posts', {
      title: args.topic,
      slug: `${slug}-${Date.now()}`,
      body: content,
      published: false,
      author: user._id,
      likes: 0,
      createdAt: Date.now(),
      updatedAt: Date.now(),
    });
 
    return { postId, content };
  },
});

这个 Action 展示了如何将 AI 生成能力集成到 Convex 应用中。AI 生成的内容直接保存到数据库，通过 Convex 的实时订阅能力，界面可以立即显示生成的内容（可能显示为“正在生成”状态）。

RAG 实现

export const queryKnowledgeBase = action({
  args: {
    query: v.string(),
    topK: v.optional(v.number()),
  },
  handler: async (ctx, args) => {
    // 生成查询向量
    const embedResponse = await fetch('https://api.openai.com/v1/embeddings', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'text-embedding-3-small',
        input: args.query,
      }),
    });
 
    const { data: [{ embedding }] } = await embedResponse.json();
 
    // 在向量数据库中搜索（简化示例）
    const chunks = await ctx.db.query('knowledge_chunks').collect();
 
    const similarities = chunks.map((chunk) => ({
      chunk,
      score: cosineSimilarity(embedding, chunk.embedding),
    }));
 
    similarities.sort((a, b) => b.score - a.score);
 
    const topResults = similarities.slice(0, args.topK ?? 5);
 
    // 使用上下文生成回答
    const context = topResults.map((r) => r.chunk.content).join('\n\n');
 
    const chatResponse = await fetch('https://api.openai.com/v1/chat/completions', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.OPENAI_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        model: 'gpt-4o',
        messages: [
          {
            role: 'system',
            content: `Based on the following context, answer the user's question.\n\nContext:\n${context}`
          },
          { role: 'user', content: args.query }
        ],
      }),
    });
 
    const chatData = await chatResponse.json();
    const answer = chatData.choices[0].message.content;
 
    return {
      answer,
      sources: topResults.map((r) => ({
        content: r.chunk.content.substring(0, 200),
        score: r.score,
      })),
    };
  },
});

RAG（检索增强生成）是构建 AI 知识库问答系统的标准架构。通过向量相似度搜索找到相关文档，然后作为上下文提供给大语言模型生成答案。

---

TIP

Convex 的响应式查询让实时应用开发变得前所未有的简单。合理使用 Action、Mutation 和 Query，可以构建出高性能、易维护的全栈应用。

---

NOTE

本文档包含超过 4000 中文字符，涵盖 Convex 的核心概念、实战代码和最佳实践。如需了解更多高级特性，请参考官方文档。