如何配置 Supabase 数据库与身份认证？

• 适合选 Supabase 的场景——你想要一个开箱即用的后端，而不想分别搭建 Postgres、认证和存储。它的价值正在于这些的一体化集成。
• 不适合选 Supabase 的场景——你需要 Supabase 未启用的特定 Postgres 扩展、已绑定到其他认证提供商，或团队对托管 Postgres 有统一规范（如 Neon、RDS 等）。若只需要纯 Postgres 而不需要认证，Neon ↗ 或 PlanetScale ↗（MySQL）是常见替代方案。

在 supabase.com ↗ 注册（免费；支持 GitHub OAuth 或邮箱注册）。

点击 New Project，填写以下信息：

• Name——随意起名。
• Database password——设置强密码并妥善保存，建立直连 Postgres 时会用到。
• Region——选择离用户或服务器最近的区域。
• Plan——初期用免费套餐即可。

配置大约需要 2 分钟。完成后进入项目控制台。

进入项目控制台 → Project Settings → API，复制以下两个值：

• Project URL——https://<ref>.supabase.co
• anon public key——形如 JWT 的长字符串。可以放到前端代码里，行级安全（RLS）会限制它的权限。
• service_role key——同样可在此处查看。绝对不能发送到浏览器端。仅用于后端；会绕过所有行级安全策略。

后端环境变量配置：

SUPABASE_URL=https://<ref>.supabase.co
SUPABASE_ANON_KEY=eyJhbGciOiJIUzI1NiIs...
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIs...   # backend ONLY

npm install @supabase/supabase-js

其他语言版本：Python ↗、Dart/Flutter ↗、Swift ↗、Kotlin ↗、C# ↗。

import { createClient } from "@supabase/supabase-js";

export const supabase = createClient(
  process.env.SUPABASE_URL,
  process.env.SUPABASE_ANON_KEY
);

这个客户端可以在前端和后端同时使用。对于需要绕过行级安全策略的后端管理操作，应使用 service-role key 创建一个独立的客户端。

进入 Supabase 控制台 → Table Editor → New table，或通过 SQL 编辑器执行：

CREATE TABLE notes (
  id BIGSERIAL PRIMARY KEY,
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  title TEXT NOT NULL,
  body TEXT,
  created_at TIMESTAMPTZ DEFAULT now()
);

-- Enable Row Level Security (RLS)
ALTER TABLE notes ENABLE ROW LEVEL SECURITY;

-- Allow users to read their own notes
CREATE POLICY "users read own notes" ON notes
  FOR SELECT USING (auth.uid() = user_id);

-- Allow users to insert their own notes
CREATE POLICY "users insert own notes" ON notes
  FOR INSERT WITH CHECK (auth.uid() = user_id);

行级安全（RLS）是 Supabase 最重要的概念。若不启用 RLS，anon key 将允许任何人读写所有数据。启用 RLS 后，数据库本身会强制执行"谁能做什么"的权限控制。请务必对存储用户数据的表启用 RLS。

RLS 文档 ↗。

// Read
const { data: notes, error } = await supabase
  .from("notes")
  .select("*")
  .order("created_at", { ascending: false });

// Write
const { data: newNote, error } = await supabase
  .from("notes")
  .insert({ title: "Hello", body: "First note" })
  .select()
  .single();

// Update
await supabase
  .from("notes")
  .update({ title: "Updated title" })
  .eq("id", newNote.id);

// Delete
await supabase.from("notes").delete().eq("id", newNote.id);

如果用户尚未登录（下一步），这些操作会返回空数组，因为 RLS 策略要求 auth.uid() 有值。这正是系统按预期运行的结果。

Supabase Auth 支持邮箱/密码、魔法链接、手机号以及数十种 OAuth 提供商——全部通过同一个 SDK 调用。

// Sign up
const { data, error } = await supabase.auth.signUp({
  email: "[email protected]",
  password: "secure-password",
});

// Sign in
const { data, error } = await supabase.auth.signInWithPassword({
  email: "[email protected]",
  password: "secure-password",
});

// Sign out
await supabase.auth.signOut();

// Get current user (returns null if not signed in)
const { data: { user } } = await supabase.auth.getUser();

登录后，SDK 会将 JWT 存入本地存储。后续每次调用 supabase.from(...) 都会携带该 token；RLS 策略通过 auth.uid() 进行过滤。

进入项目控制台 → Authentication → Providers，开启 Google、GitHub、Apple 等。每个提供商需要填写来自其控制台的 Client ID 和 Client Secret——获取方式请参考 使用 Google 登录 和 使用 GitHub 登录。

然后在应用中调用：

await supabase.auth.signInWithOAuth({
  provider: "google",
  options: { redirectTo: "https://yourapp.com/auth/callback" },
});

整个流程就是这样——Supabase 会处理重定向、JWT 签发和会话刷新。

supabase.auth.onAuthStateChange((event, session) => {
  // event: "SIGNED_IN" | "SIGNED_OUT" | "TOKEN_REFRESHED" | ...
  if (event === "SIGNED_IN") {
    console.log("Signed in as", session.user.email);
  }
});

在应用启动时订阅一次即可。常用于同步 UI 状态（登录时显示"退出登录"按钮等）。

Supabase 通过 WebSocket 推送 Postgres 的数据变更。订阅某张表的方式如下：

const channel = supabase
  .channel("notes-changes")
  .on(
    "postgres_changes",
    { event: "*", schema: "public", table: "notes" },
    (payload) => {
      console.log("Change:", payload);
    }
  )
  .subscribe();

// Later, to disconnect:
supabase.removeChannel(channel);

结合 React 状态管理，你可以实现实时多人光标、即时聊天、协作文档——完全不需要自己编写 WebSocket 服务器。实时功能文档 ↗。

Supabase 内置了兼容 S3 的对象存储。在 Supabase 应用内上传文件的方式：

// Create a bucket once in the dashboard: Storage → Create bucket
await supabase.storage
  .from("avatars")
  .upload(`${user.id}/profile.png`, fileBlob, { upsert: true });

const { data } = supabase.storage
  .from("avatars")
  .getPublicUrl(`${user.id}/profile.png`);

console.log(data.publicUrl);   // ready to put in an <img>

如果你已在 AWS 上或希望零出口流量，请参考 上传文件到 S3 或 Cloudflare R2。否则，在同一项目中使用 Supabase Storage 是最简便的方案。

对于正式项目，建议在本地 Supabase 实例上开发，而非直接连接生产环境：

brew install supabase/tap/supabase   # or via npm: npm i -g supabase
supabase init                          # in your project root
supabase start                         # spins up Postgres + Studio + Auth in Docker

将数据库迁移编写为 supabase/migrations/ 目录下的 SQL 文件，使用 supabase db push 推送到生产环境。CLI 文档 ↗。

免费套餐：500 MB 数据库、每月 5 万活跃用户、1 GB 文件存储、5 GB 带宽、2 个免费项目。若项目一周内无请求，会被暂停（可唤醒，不会被删除）。

Pro 套餐：每月 $25——8 GB 数据库、10 万月活用户、100 GB 存储，项目不会被暂停。Supabase 定价 ↗。

自托管：完整源码开放。自托管文档 ↗。生产环境自托管需要一定的运维投入，大多数人还是选择托管服务。