Convex 快速入门

只需几分钟即可搭建好生产可用的Convex后端。本指南将引导你完成Convex初始化、Schema创建、认证设置以及首个CRUD操作的构建。

适用场景

使用Convex启动全新项目
为现有React/Next.js应用添加Convex
基于实时数据原型化新功能
从其他后端迁移至Convex
首次向他人讲解Convex

前置条件检查

开始前，请确认：

bash

node --version  # v18 或更高版本
npm --version   # v8 或更高版本

快速入门流程

步骤1：安装与初始化

bash

# 安装Convex
npm install convex

# 初始化（创建convex/目录）
npx convex dev

该命令会：

创建
```
convex/
```
目录
配置认证
启动开发服务器
生成TypeScript类型定义

步骤2：创建Schema

创建

convex/schema.ts

：

typescript

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

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

  // 在此添加你的数据表
  // 示例：任务表
  tasks: defineTable({
    userId: v.id("users"),
    title: v.string(),
    completed: v.boolean(),
    createdAt: v.number(),
  })
    .index("by_user", ["userId"])
    .index("by_user_and_completed", ["userId", "completed"]),
});

步骤3：设置认证

我们将使用WorkOS AuthKit，它能以极少的配置提供完整的认证解决方案。

bash

npm install @workos-inc/authkit-react

适用于React/Vite应用：

typescript

// src/main.tsx
import { AuthKitProvider, useAuth } from "@workos-inc/authkit-react";
import { ConvexReactClient } from "convex/react";
import { ConvexProvider } from "convex/react";

const convex = new ConvexReactClient(import.meta.env.VITE_CONVEX_URL);

// 配置Convex使用WorkOS认证
convex.setAuth(useAuth);

function App() {
  return (
    <AuthKitProvider>
      <ConvexProvider client={convex}>
        <YourApp />
      </ConvexProvider>
    </AuthKitProvider>
  );
}

适用于Next.js应用：

bash

npm install @workos-inc/authkit-nextjs

typescript

// app/layout.tsx
import { AuthKitProvider } from "@workos-inc/authkit-nextjs";
import { ConvexClientProvider } from "./ConvexClientProvider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <AuthKitProvider>
          <ConvexClientProvider>
            {children}
          </ConvexClientProvider>
        </AuthKitProvider>
      </body>
    </html>
  );
}

typescript

// app/ConvexClientProvider.tsx
"use client";

import { ConvexReactClient } from "convex/react";
import { ConvexProvider } from "convex/react";
import { useAuth } from "@workos-inc/authkit-nextjs";

const convex = new ConvexReactClient(process.env.NEXT_PUBLIC_CONVEX_URL!);

export function ConvexClientProvider({ children }: { children: React.ReactNode }) {
  const { getToken } = useAuth();

  convex.setAuth(async () => {
    return await getToken();
  });

  return <ConvexProvider client={convex}>{children}</ConvexProvider>;
}

环境变量：

bash

# .env.local
VITE_CONVEX_URL=https://your-deployment.convex.cloud
VITE_WORKOS_CLIENT_ID=your_workos_client_id

# 适用于Next.js：
NEXT_PUBLIC_CONVEX_URL=https://your-deployment.convex.cloud
NEXT_PUBLIC_WORKOS_CLIENT_ID=your_workos_client_id
WORKOS_API_KEY=your_workos_api_key
WORKOS_COOKIE_PASSWORD=generate_a_random_32_character_string

替代认证提供商： 若需使用其他提供商（Clerk、Auth0、自定义JWT），请查看Convex认证文档。

步骤4：创建认证工具函数

创建

convex/lib/auth.ts

：

typescript

import { QueryCtx, MutationCtx } from "../_generated/server";
import { Doc } from "../_generated/dataModel";

export async function getCurrentUser(
  ctx: QueryCtx | MutationCtx
): Promise<Doc<"users">> {
  const identity = await ctx.auth.getUserIdentity();
  if (!identity) {
    throw new Error("Not authenticated");
  }

  const user = await ctx.db
    .query("users")
    .withIndex("by_token", q =>
      q.eq("tokenIdentifier", identity.tokenIdentifier)
    )
    .unique();

  if (!user) {
    throw new Error("User not found");
  }

  return user;
}

创建

convex/users.ts

：

typescript

import { mutation } from "./_generated/server";

export const store = mutation({
  args: {},
  handler: async (ctx) => {
    const identity = await ctx.auth.getUserIdentity();
    if (!identity) throw new Error("Not authenticated");

    const existing = await ctx.db
      .query("users")
      .withIndex("by_token", q =>
        q.eq("tokenIdentifier", identity.tokenIdentifier)
      )
      .unique();

    if (existing) return existing._id;

    return await ctx.db.insert("users", {
      tokenIdentifier: identity.tokenIdentifier,
      name: identity.name ?? "Anonymous",
      email: identity.email ?? "",
    });
  },
});

步骤5：创建首个CRUD操作

创建

convex/tasks.ts

：

typescript

import { query, mutation } from "./_generated/server";
import { v } from "convex/values";
import { getCurrentUser } from "./lib/auth";

// 列出当前用户的所有任务
export const list = query({
  args: {},
  handler: async (ctx) => {
    const user = await getCurrentUser(ctx);
    return await ctx.db
      .query("tasks")
      .withIndex("by_user", q => q.eq("userId", user._id))
      .order("desc")
      .collect();
  },
});

// 获取单个任务
export const get = query({
  args: { taskId: v.id("tasks") },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    const task = await ctx.db.get(args.taskId);

    if (!task) throw new Error("Task not found");
    if (task.userId !== user._id) throw new Error("Unauthorized");

    return task;
  },
});

// 创建任务
export const create = mutation({
  args: { title: v.string() },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    return await ctx.db.insert("tasks", {
      userId: user._id,
      title: args.title,
      completed: false,
      createdAt: Date.now(),
    });
  },
});

// 更新任务
export const update = mutation({
  args: {
    taskId: v.id("tasks"),
    title: v.optional(v.string()),
    completed: v.optional(v.boolean()),
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    const task = await ctx.db.get(args.taskId);

    if (!task) throw new Error("Task not found");
    if (task.userId !== user._id) throw new Error("Unauthorized");

    const updates: any = {};
    if (args.title !== undefined) updates.title = args.title;
    if (args.completed !== undefined) updates.completed = args.completed;

    await ctx.db.patch(args.taskId, updates);
  },
});

// 删除任务
export const remove = mutation({
  args: { taskId: v.id("tasks") },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);
    const task = await ctx.db.get(args.taskId);

    if (!task) throw new Error("Task not found");
    if (task.userId !== user._id) throw new Error("Unauthorized");

    await ctx.db.delete(args.taskId);
  },
});

步骤6：在React应用中使用

typescript

// app/tasks/page.tsx
"use client";

import { useQuery, useMutation } from "convex/react";
import { api } from "../../convex/_generated/api";

export default function TasksPage() {
  const tasks = useQuery(api.tasks.list);
  const create = useMutation(api.tasks.create);
  const update = useMutation(api.tasks.update);
  const remove = useMutation(api.tasks.remove);

  if (!tasks) return <div>Loading...</div>;

  return (
    <div>
      <h1>Tasks</h1>

      {/* 创建任务 */}
      <form onSubmit={(e) => {
        e.preventDefault();
        const formData = new FormData(e.target as HTMLFormElement);
        create({ title: formData.get("title") as string });
        (e.target as HTMLFormElement).reset();
      }}>
        <input name="title" placeholder="New task..." />
        <button>Add</button>
      </form>

      {/* 任务列表 */}
      {tasks.map(task => (
        <div key={task._id}>
          <input
            type="checkbox"
            checked={task.completed}
            onChange={(e) => update({
              taskId: task._id,
              completed: e.target.checked
            })}
          />
          <span>{task.title}</span>
          <button onClick={() => remove({ taskId: task._id })}>
            Delete
          </button>
        </div>
      ))}
    </div>
  );
}

步骤7：开发环境与生产环境

开发环境（推荐使用！）：

bash

# 启动开发服务器（请勿用于生产！）
npx convex dev

# 本地运行，变更时自动重载
# 所有开发工作请使用此命令

生产环境部署：

bash

# 仅在部署至生产环境时使用！
npx convex deploy

# 警告：此命令会部署至你的生产环境
# 开发过程中请勿使用

重要提示： 开发期间请始终使用

npx convex dev

。仅当准备好上线生产时，再使用

npx convex deploy

。

常见模式

分页查询

typescript

export const listPaginated = query({
  args: {
    cursor: v.optional(v.string()),
    limit: v.number(),
  },
  handler: async (ctx, args) => {
    const user = await getCurrentUser(ctx);

    const results = await ctx.db
      .query("tasks")
      .withIndex("by_user", q => q.eq("userId", user._id))
      .order("desc")
      .paginate({ cursor: args.cursor, limit: args.limit });

    return results;
  },
});

定时任务

typescript

// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";

const crons = cronJobs();

crons.daily(
  "cleanup-old-tasks",
  { hourUTC: 0, minuteUTC: 0 },
  internal.tasks.cleanupOld
);

export default crons;

项目模板

React + Vite + Convex

bash

npm create vite@latest my-app -- --template react-ts
cd my-app
npm install convex @workos-inc/authkit-react
npx convex dev

Next.js + Convex

bash

npx create-next-app@latest my-app
cd my-app
npm install convex @workos-inc/authkit-nextjs
npx convex dev

Expo（React Native）+ Convex

bash

npx create-expo-app my-app
cd my-app
npm install convex
npx convex dev

检查清单

已完成
```
npm install convex
```
```
npx convex dev
```
正在运行（请使用此命令，而非deploy！）
已创建带正确索引的Schema
已配置认证提供商（WorkOS/自定义）
已实现
```
getCurrentUser
```
工具函数
已创建用户存储mutation
已创建带认证检查的CRUD操作
前端已与hooks集成
已在本地测试查询与mutation
准备好生产部署时，使用
```
npx convex deploy
```

后续步骤

完成快速入门后：

为Schema添加更多数据表
实现数据表间的关联关系
添加文件存储（Convex支持文件上传）
为AI功能设置向量搜索
添加定时任务
配置生产环境变量

故障排除

"Not authenticated"错误

确保认证提供商已正确配置
首次登录时调用
```
storeUser
```
mutation
检查
```
getCurrentUser
```
是否正确导入

类型未更新

运行
```
npx convex dev
```
（重新生成类型）
重启编辑器中的TypeScript服务器

查询缓慢

为Schema添加索引
使用
```
.withIndex()
```
替代
```
.filter()
```
在控制台中检查查询模式

convex-quickstart

NPX安装

标签

SKILL.md 内容（中文）

Convex 快速入门

适用场景

前置条件检查

快速入门流程

步骤1：安装与初始化

步骤2：创建Schema

步骤3：设置认证

适用于React/Vite应用：

适用于Next.js应用：

环境变量：

步骤4：创建认证工具函数

步骤5：创建首个CRUD操作

步骤6：在React应用中使用

步骤7：开发环境与生产环境

常见模式

分页查询

定时任务

项目模板

React + Vite + Convex

Next.js + Convex

Expo（React Native）+ Convex

检查清单

后续步骤

故障排除

"Not authenticated"错误

类型未更新

查询缓慢

更多学习资源