使用Convex

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

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

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

🌐 The EAS CLI integration can create and connect the Convex project for you. It replaces the manual setup steps where you install the package, create a Convex team and project, copy deployment URLs, and configure EAS environment variables.

先决条件

3 要求

Expo 账户

注册一个 Expo 账号。

EAS 命令行接口

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

Expo 项目已链接到 EAS

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

将 Convex 连接到 EAS

🌐 Connect Convex with EAS

运行 EAS CLI 集成命令

🌐 Run the EAS CLI integration command

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

🌐 From your Expo project directory, run:

Terminal

- eas integrations:convex:connect

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

🌐 The command will prompt for a Convex deployment region, project name, and team name when needed. It only asks for a team name when it needs to create a new Convex team connection.

你也可以显式传递值：

🌐 You can also pass values explicitly:

Terminal

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

集成命令：

🌐 The integration command:

使用 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

🌐 Start Convex locally

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

🌐 After the integration command finishes, start the Convex dev server:

Terminal

- npx convex dev

- yarn dlx convex dev

- pnpm dlx convex dev

- bunx convex dev

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

🌐 This creates the local convex directory if your project does not have one yet, generates the typed API files, and syncs your Convex functions with your deployment while it runs.

添加 Convex 提供者

🌐 Add a Convex provider

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

🌐 Create a Convex client with the deployment URL that the EAS integration wrote to .env.local, then wrap your app in ConvexProvider.

对于一个 Expo Router 项目，更新 src/app/_layout.tsx:

🌐 For an Expo Router project, update 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

🌐 Query Convex from your app

在 convex 目录中添加查询功能：

🌐 Add a query function in the convex directory:

convex/tasks.ts

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

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

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

🌐 Then call it from your app with 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 概述：

🌐 To learn more about how Convex works, including database documents, functions, and client subscriptions, see the Convex overview:

凸面概览

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

管理整合

🌐 Manage the integration

稍后使用这些命令来检查或管理 Convex 集成：

🌐 Use these commands to inspect or manage the Convex integration later:

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 上的资源。

🌐 If you remove the link with eas integrations:convex:project:delete or eas integrations:convex:team:delete, EAS removes its integration metadata. These commands do not destroy resources on Convex.

故障排除

🌐 Troubleshooting

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

🌐 Accept a team invite sent to a different email

Convex 团队的邀请会发到你 Expo 账号上验证过的邮箱，但 Convex 只支持用 Google 或 GitHub 登录。如果你的 Google 或 GitHub 邮箱和这个不同，邀请页面会提示被邀请的邮箱地址还没有添加到你的 Convex 账号里。离开那个页面后，你会进入一个独立的 Convex 账号，里面没有你的项目。

🌐 The Convex team invitation goes to the verified email on your Expo account, but Convex only supports signing in with Google or GitHub. If your Google or GitHub email is different, the invitation page says the invited email address has not been added to your Convex account. Navigating away from that page leaves you in a separate Convex account that does not contain your project.

Convex invitation page showing that the email address associated with the team invitation has not been added to your account

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

🌐 To accept the invite from your existing Convex account:

在邀请页面（或 Convex 仪表盘的个人资料设置中），点击添加邮箱并输入被邀请的邮箱地址。
打开 Convex 发送到该邮箱的验证邮件并进行验证。
返回邀请链接并重新加载页面，或者退出登录后再次打开邀请链接。
接受邀请。团队和项目现在出现在你的 Convex 账户里。

信息在验证电子邮件后，流程可能看起来像失败了。邀请页面在重新加载或重新打开之前不会更新。