使用 Convex

编辑页面

使用 Convex 为你的应用添加数据库。

Convex 是一个后端平台，用于构建具有实时数据库、服务器函数、文件存储、搜索、调度以及类型安全客户端库的响应式应用，而无需集群管理、SQL 或 ORM。

EAS CLI 集成可以为你创建并连接 Convex 项目。它替代了手动设置步骤，例如安装包、创建 Convex 团队和项目、复制部署 URL，以及配置 EAS 环境变量。

Prerequisites

3 requirements

Expo 账户

注册一个 Expo 账户。

EAS CLI

使用 npm install -g eas-cli 全局安装 EAS CLI。

已链接到 EAS 的 Expo 项目

创建一个 Expo 项目，并使用 eas init 将其链接到 EAS。

使用 EAS 连接 Convex

运行 EAS CLI 集成命令

在你的 Expo 项目目录中运行：

Terminal

- eas integrations:convex:connect

在需要时，该命令会提示你输入 Convex 部署区域、项目名称和团队名称。只有在需要创建新的 Convex 团队连接时，它才会询问团队名称。

你也可以显式传入这些值：

Terminal

- eas integrations:convex:connect --region aws-us-east-1 --team-name "Your-team-name" --project-name "your-app"

该集成命令会：

使用 npx expo install convex 安装 convex 包
为你的 EAS 账户创建一个 Convex 团队连接，或复用已有连接
为当前 Expo 应用创建一个 Convex 项目和部署
将 CONVEX_DEPLOY_KEY 和 EXPO_PUBLIC_CONVEX_URL 写入 .env.local
为生产、预览和开发环境创建或更新 EXPO_PUBLIC_CONVEX_URL EAS 项目环境变量
向你已验证的邮箱发送邀请，以便你可以认领 Convex 团队并打开 Convex 仪表盘

在本地启动 Convex

集成命令完成后，启动 Convex 开发服务器：

Terminal

- npx convex dev

如果你的项目还没有 convex 目录，这会创建一个本地目录，生成类型化的 API 文件，并在运行时将你的 Convex 函数与部署同步。

添加 Convex provider

使用 EAS 集成写入 .env.local 的部署 URL 创建一个 Convex 客户端，然后用 ConvexProvider 包裹你的应用。

对于 Expo Router 项目，请更新 src/app/_layout.tsx：

src/app/_layout.tsx

import { ConvexProvider, ConvexReactClient } from 'convex/react';
import { Stack } from 'expo-router';

const convex = new ConvexReactClient(process.env.EXPO_PUBLIC_CONVEX_URL!, {
  unsavedChangesWarning: false,
});

export default function RootLayout() {
  return (
    <ConvexProvider client={convex}>
      <Stack />
    </ConvexProvider>
  );
}

从你的应用中查询 Convex

在 convex 目录中添加一个查询函数：

convex/tasks.ts

import { query } from './_generated/server';

export const get = query({
  args: {},
  handler: async ctx => {
    return await ctx.db.query('tasks').collect();
  },
});

然后在你的应用中使用 useQuery 调用它：

src/app/index.tsx

import { api } from '@/convex/_generated/api';
import { useQuery } from 'convex/react';
import { Text, View } from 'react-native';

export default function Index() {
  const tasks = useQuery(api.tasks.get);

  return (
    <View>
      {tasks?.map(task => (
        <Text key={task._id}>{task.text}</Text>
      ))}
    </View>
  );
}

要了解 Convex 的更多工作原理，包括数据库文档、函数和客户端订阅，请参阅 Convex 概览：

Convex 概览

了解数据库文档、函数和实时客户端更新背后的核心 Convex 概念。

管理集成

之后可使用这些命令来查看或管理 Convex 集成：

Terminal

- eas integrations:convex:project

- eas integrations:convex:dashboard

- eas integrations:convex:team

- eas integrations:convex:team:invite

如果使用 eas integrations:convex:project:delete 或 eas integrations:convex:team:delete 移除链接，EAS 会删除其集成元数据。这些命令不会销毁 Convex 上的资源。

故障排除

接受发送到其他邮箱的团队邀请

Convex 团队邀请会发送到你 Expo 账户中已验证的邮箱，但 Convex 仅支持使用 Google 或 GitHub 登录。如果你的 Google 或 GitHub 邮箱不同，邀请页面会显示受邀邮箱地址尚未添加到你的 Convex 账户。离开该页面后，你会进入一个不包含项目的独立 Convex 账户。

要从现有的 Convex 账户接受邀请：

在邀请页面（或 Convex 控制面板的个人资料设置中）点击添加邮箱，然后输入受邀邮箱地址。
打开 Convex 发送到该地址的验证邮件并完成验证。
返回邀请链接并重新加载页面，或退出登录后再次打开邀请链接。
接受邀请。此时，团队和项目就会显示在你的 Convex 账户中。

验证邮箱后，该流程看起来可能像是失败了。重新加载或重新打开邀请页面之前，邀请页面不会更新。