This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

使用 Supabase 在你的 React Native 应用中添加 Postgres 数据库和用户认证。

Supabase 是一个基于 Postgres 构建的后端即服务 (BaaS) 应用开发平台。它可以从你的数据库生成 REST API，并使用行级安全来保护数据，所以你的 React Native 应用可以直接查询这个 API，中间不需要服务器。

EAS CLI 集成可以自动补齐标准设置：授权你的 Supabase 账户、创建或关联项目、安装 SDK，并填写环境变量。你也可以手动设置并照常使用本指南的其他部分。

🌐 The EAS CLI integration automates the standard setup: authorizing your Supabase account, creating or linking a project, installing the SDK, and writing your environment variables. You can also set it up manually and use the rest of this guide unchanged.

你将学到什么

🌐 What you'll learn

• 在你的 React Native 应用中安装和配置 Supabase
• [使用你在步骤2中创建的客户端]添加身份验证
• 为本地开发、生产环境和预览环境 设置环境
• 管理集成 和 排查常见问题

安装并配置 Supabase

🌐 Install and configure Supabase

import 'expo-sqlite/localStorage/install';
import { createClient } from '@supabase/supabase-js';

const supabaseUrl = process.env.EXPO_PUBLIC_SUPABASE_URL!;
const supabasePublishableKey = process.env.EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY!;

export const supabase = createClient(supabaseUrl, supabasePublishableKey, {
  auth: {
    storage: localStorage,
    autoRefreshToken: true,
    persistSession: true,
    detectSessionInUrl: false,
  },
});

create table public.todos (
  id bigint generated always as identity primary key,
  title text not null
);
alter table public.todos enable row level security;
create policy "Anyone can read todos" on public.todos for select using (true);
grant select on public.todos to anon, authenticated;
insert into public.todos (title) values ('Hello from Supabase');

import { useEffect, useState } from 'react';
import { Text, View } from 'react-native';
import { supabase } from '@/lib/supabase';

export default function Index() {
  const [titles, setTitles] = useState<string[]>([]);

  useEffect(() => {
    supabase
      .from('todos')
      .select()
      .then(({ data, error }) => {
        if (error) {
          setTitles([error.message]);
          return;
        }
        setTitles(data.map(todo => todo.title));
      });
  }, []);

  return (
    <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
      {titles.map(title => (
        <Text key={title}>{title}</Text>
      ))}
    </View>
  );
}

有关这些步骤背后的概念，请参阅 Supabase 数据库概览：

🌐 For the concepts behind these steps, see the Supabase database overview:

添加身份验证

🌐 Add authentication

来自 Step 2 的客户端已经存储了会话，所以使用邮箱和密码登录不需要额外配置。新的 Supabase 项目默认会确认邮箱地址。你的第一个 signUp 会返回 data.user，并且 data.session 会设置为 null，直到地址被确认，或者你在项目的邮箱提供商设置中关闭 确认邮箱。

🌐 The client from Step 2 already stores sessions, so email and password sign-in needs no extra configuration. New Supabase projects confirm email addresses by default. Your first signUp returns data.user with data.session set to null until the address is confirmed or you turn off Confirm email in your project's email provider settings.

autoRefreshToken 会在 Android 和 iOS 上持续运行其刷新循环，所以 Supabase 的 startAutoRefresh 参考 建议将循环绑定到应用状态。在你的客户端文件中添加这个内容:

import { AppState } from 'react-native';

AppState.addEventListener('change', state => {
  if (state === 'active') {
    supabase.auth.startAutoRefresh();
  } else {
    supabase.auth.stopAutoRefresh();
  }
});

OAuth 提供商和魔术链接需要一个深度链接返回到你的应用，详见 Supabase 的移动深度链接指南。

🌐 OAuth providers and magic links need a deep link back into your app, covered in Supabase's mobile deep linking guide.

设置环境

🌐 Set up environments

connect 将这些值存储为 EAS 环境变量，所以每次构建或更新都会从运行的环境中读取它们。

一个 Supabase 项目包含一个环境的数据，所以不同的环境就意味着要有不同的项目。在创建第二个项目之前，先查看你的 Supabase 计划限制。

🌐 A Supabase project holds one environment's data, so separate environments mean separate projects. Check your Supabase plan limits before creating a second project.

开发 可以在本地使用 Supabase CLI 运行。先启动 Docker，然后运行：

用 supabase status 打印的 API URL 和可发布密钥替换 .env.local 中的托管值。你在 shell 中导出的变量优先于 .env.local，所以编辑文件就行，不用导出。因为本地数据库是空的，所以也要对它运行你的表 SQL。重新运行 connect 会把托管值写回去。

🌐 Replace the hosted values in .env.local with the API URL and publishable key that supabase status prints. Variables you export in your shell take precedence over .env.local, so edit the file instead of exporting. The local database starts empty, so run your table SQL against it too. Re-running connect writes the hosted values back.

信息 本地 URL 指向你的电脑。物理设备或 Android 模拟器无法访问它，所以在那儿使用你电脑的局域网地址，而不是 127.0.0.1。

生产 使用 connect 设置的项目。

预览 默认没有自己的项目。要给预览或任何其他 EAS 环境分配自己的托管项目，请使用 --environment 重新运行 connect。这将创建第二个项目，并计入你计划的活跃项目限制：

新项目的 URL 和密钥只会指向指定的环境，而你的其他环境仍然指向第一个项目。如果目标环境中已经有 EXPO_PUBLIC_SUPABASE_* 值，命令会在替换前要求确认。和没有 --environment 的 connect 不同，这不会安装 SDK，也不会修改 .env.local。你不能将 --environment 和 --link、--reauth 或 --organization 结合使用。

🌐 The new project's URL and key go to the named environments only, and your other environments keep pointing at the first project. If the target environments already hold EXPO_PUBLIC_SUPABASE_* values, the command asks to confirm before replacing them. Unlike connect without --environment, this doesn't install the SDK or touch .env.local. You can't combine --environment with --link, --reauth, or --organization.

要让 EAS 环境指向你已有的 Supabase 项目，可以自己用 eas env:set 设置这两个变量，而不是使用 --environment。先用两个替换共享变量，如上所示，这样你的其他环境就能保持当前项目不变。

🌐 To point an EAS environment at a Supabase project you already have, set the two variables yourself with eas env:set rather than using --environment. Replace the shared variable with two first, as shown above, so your other environments keep their current project.

管理整合

🌐 Manage the integration

之后有两个命令来管理集成：

🌐 Two commands manage the integration afterward:

dashboard 会打开你已关联的 Supabase 项目。disconnect 只会移除 Expo 端的关联。你的 Supabase 项目、数据以及环境变量都不会受影响。

断开连接后，connect 不再看到已关联的项目，因此它会创建一个新项目。要让应用指回同一个项目，运行带有其参考ID的 connect --link 就可以了。

🌐 After you disconnect, connect no longer sees a linked project, so it creates a new one. To point the app back at the same project, run connect --link with its reference ID.

手动设置

🌐 Manual setup

connect 是标准 Supabase 设置的快捷方式。要手动操作的话：

1. 在 database.new 创建一个项目。

2. 从 API 设置 复制 项目 URL，从 API 密钥 复制 可发布的密钥。

3. 安装 SDK：

   Terminalnpmyarnpnpmbun

   复制

   - npx expo install @supabase/supabase-js expo-sqlite

   - yarn expo install @supabase/supabase-js expo-sqlite

   - pnpm expo install @supabase/supabase-js expo-sqlite

   - bun expo install @supabase/supabase-js expo-sqlite

4. 将 expo-sqlite 配置插件添加到你的 应用配置 中。

5. 在 .env.local 中设置 EXPO_PUBLIC_SUPABASE_URL 和 EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY，然后从 步骤 2 创建客户端文件。

故障排除

🌐 Troubleshooting

进一步阅读

🌐 Further reading