Supabase 完全指南

💡 免費起步：Supabase 提供免費方案，免綁信用卡 就能建立專案，內含一個完整 Postgres、認證、儲存與即時功能，足以做原型甚至小型上線。實際操作見 快速開始。

目錄

• 什麼是 Supabase？
• 架構與元件
• 核心功能
• 快速開始（免費）
• Row Level Security（RLS）
• 自動產生的 API
• 連線機制（重點）
• 計費模型
• 什麼情境適合用 Supabase？
• Supabase vs Firebase
• 實戰範例
• 最佳實踐
• 常見問題
• 總結

什麼是 Supabase？

Supabase 是一個 開源的後端即服務（BaaS）平台，常被稱為「開源的 Firebase 替代方案」。它的核心理念是：一切建立在 Postgres 之上。每開一個專案，就得到一個專屬的完整 Postgres 資料庫，再加上一整套圍繞它的後端服務。

一句話理解

Firebase   = 後端服務全包，但核心是 NoSQL（Firestore），且封閉
Supabase   = 後端服務全包，但核心是 Postgres（關聯式 + SQL），且開源

它把「開發一個應用後端會用到的東西」打包好：資料庫、使用者認證、檔案儲存、即時訂閱、自動 API、邊緣函數——讓你不用自己一個個架。

核心定位

Supabase = Postgres + Auth + Storage + Realtime + 自動 API + Edge Functions
           （全部開源，可自架，也可用託管雲）

• 不是 一個全新的私有資料庫，而是 標準 Postgres + 一層服務生態
• 因為底層就是 Postgres，你隨時能用任何 Postgres 工具、SQL、擴充套件，不會被鎖死

架構與元件

Supabase 不是單一程式，而是一組 開源服務的組合，前面用 API 閘道統一入口，全部連到 同一個 Postgres 實例：

         ┌─────────────── Kong（API Gateway，基於 NGINX）───────────────┐
         │                                                              │
 客戶端 ─┤  /auth     → GoTrue（認證，Go）                              │
         │  /rest     → PostgREST（自動 REST API，Haskell）             │
         │  /realtime → Realtime（WebSocket 引擎，Elixir）              │
         │  /storage  → Storage（S3 相容物件儲存，Node/TS）             │
         │  /graphql  → pg_graphql（自動 GraphQL）                      │
         │  /functions→ Edge Functions（Deno）                          │
         │                                                              │
         └──────────────────────┬───────────────────────────────────────┘
                                 ↓ 全部指向
                        ┌─────────────────┐
                        │   Postgres DB   │  ← 單一事實來源
                        └─────────────────┘

關鍵觀念：所有服務都圍繞 同一個 Postgres。使用者帳號、檔案 metadata、即時訂閱的資料來源，全都在這個資料庫裡——所以資料權限可以用 資料庫層級的 RLS 統一管控。

核心功能

1. Database（Postgres）

每個專案就是一個完整的 Postgres：可以直接寫 SQL、建索引、用 view / trigger / function、裝擴充套件（如 pgvector 做向量、postgis 做地理）。

2. Authentication（認證）

內建使用者註冊 / 登入，支援 email 密碼、Magic Link、OAuth 第三方（Google、GitHub…）、手機 OTP 等。登入後發 JWT，並與 RLS 整合做資料授權。

3. Storage（檔案儲存）

S3 相容的物件儲存，用來存圖片、影片、文件等大型檔案。檔案的 metadata 存在 Postgres，因此 也能用 RLS 控制誰能存取哪些檔案，並支援即時影像轉換。

4. Realtime（即時）

基於 WebSocket，三種模式：

• Postgres Changes：監聽資料表的 INSERT/UPDATE/DELETE，即時推給前端
• Broadcast：對訂閱同一頻道的客戶端廣播訊息
• Presence：追蹤 / 同步使用者上線狀態（如「誰在線上」）

5. Edge Functions（邊緣函數）

以 Deno 執行的伺服器端函數，全球分散部署，在離使用者最近的節點執行，適合放自訂後端邏輯、Webhook、第三方整合。

6. Vector（向量 / AI）

透過 pgvector 擴充，直接在 Postgres 存與查向量嵌入，用於語意搜尋、RAG。

快速開始（免費）

從免費方案起步只要幾分鐘，不需要信用卡。

步驟

1. 註冊並建專案 — 到 supabase.com 用 GitHub 登入 → New Project → 選區域、設定一組資料庫密碼。專案開好後就有一個完整 Postgres。

2. 取得連線金鑰 — 到 Settings → API，複製 Project URL 與 anon public key（給前端用，安全靠 RLS 把關）。

3. 建一張表 — 用 Table Editor 點選建立，或在 SQL Editor 直接寫：

create table todos (
  id      bigint generated always as identity primary key,
  user_id uuid references auth.users,
  task    text not null,
  done    boolean default false
);

4. 開啟並設定 RLS — 這步千萬別跳過，否則整張表對所有人公開。詳見 下一節 RLS。

5. 安裝 SDK 並查詢：

npm install @supabase/supabase-js

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

const supabase = createClient(
  process.env.SUPABASE_URL,       // Project URL
  process.env.SUPABASE_ANON_KEY   // anon public key
);

const { data, error } = await supabase.from("todos").select("*");

想在本機開發？用 CLI

npm install -g supabase
supabase init     # 初始化專案設定檔
supabase start    # 用 Docker 在本機跑起整套 Supabase（DB / Auth / Storage…）

免費方案含 2 個專案、500MB 資料庫、5 萬認證 MAU、1GB 檔案儲存與即時功能，足以做原型甚至小型上線；用量成長後再升級（見 計費模型）。

Row Level Security（RLS）

這是 Supabase 安全模型的核心，務必理解。

因為前端會 直接 透過自動 API 存取資料庫（不一定經過自寫後端），所以「誰能讀寫哪一筆資料」不能只靠應用層判斷——必須在 資料庫層級 鎖死。這就是 RLS（Row Level Security，列級安全）：Postgres 原生功能，讓你對「每一筆資料列」訂授權規則。

-- 開啟資料表的 RLS（開啟後預設「全部拒絕」，要明確開放）
ALTER TABLE profiles ENABLE ROW LEVEL SECURITY;

-- 政策：使用者只能讀取「自己的」資料列
-- auth.uid() 會取出當前登入者的 JWT 使用者 ID
CREATE POLICY "users can read own profile"
ON profiles FOR SELECT
USING ( auth.uid() = user_id );

-- 政策：使用者只能更新自己的資料列
CREATE POLICY "users can update own profile"
ON profiles FOR UPDATE
USING ( auth.uid() = user_id );

核心心法：

• RLS 一旦 ENABLE，預設 所有存取都被拒絕，必須用 POLICY 明確開放
• 規則寫在資料庫，無論從前端、API、還是其他路徑來，一視同仁地被強制執行
• 這是「把授權邏輯下沉到資料庫」的設計，安全邊界清楚

常見事故：忘了開 RLS，導致整張表對所有人公開可讀寫。上線前務必檢查每張表的 RLS 狀態。

自動產生的 API

Supabase 不用你手寫 CRUD endpoint。PostgREST 會讀取你的資料庫結構（schema），自動生成對應的 RESTful API；pg_graphql 則自動產生 GraphQL API。

你在 DB 建了一張 posts 表
        ↓ PostgREST 自動產生
GET    /rest/v1/posts            → 查詢
POST   /rest/v1/posts            → 新增
PATCH  /rest/v1/posts?id=eq.1    → 更新
DELETE /rest/v1/posts?id=eq.1    → 刪除

改了資料表結構，API 自動跟著變——schema 就是 API 的單一事實來源。配合 RLS，這些自動 API 即使被前端直接呼叫也是安全的。

連線機制（重點）

跟資料庫怎麼連，Supabase 有「直連」與「連線池」兩條路，serverless 環境選錯會出事。

兩種連線方式

為什麼 serverless 一定要用連線池？

Postgres 的每條連線都吃記憶體，且連線數有上限。Serverless 函數是「短命、可能瞬間大量並行啟動」的——若每個實例都直連 Postgres，連線數很快爆掉。

Supavisor 是 Supabase 自研的 雲原生、多租戶 Postgres 連線池（以 Elixir 開發，可承接到百萬等級連線）。它取代了早期使用的 PgBouncer。讓大量短命的客戶端連線，被收斂成少量、複用的實體資料庫連線：

serverless 實例 ×N ──大量短命連線──► Supavisor（池）──少量複用連線──► Postgres

這跟一般 SQLite/Postgres 的連線池概念一致：應用端的「開 / 關連線」對應到池子的「借出 / 歸還」，底層實體連線被重複使用，而非每次真的開關。

交易模式 vs 連線階段模式

Serverless 場景通常用 交易模式 連線池，複用效率最高；需要連線階段狀態時才用 session 模式。

計費模型

幾個計費重點：

• 認證按 MAU（月活躍使用者）計費：免費 5 萬、Pro 含 10 萬，超出按每位額外 MAU 計費
• 付費方案附運算額度（約 $10/月），可抵一個小型運算實例或折抵其他規格
• 資料庫流量（egress）、儲存、邊緣函數呼叫各有額度，超出另計

注意：認證、儲存、流量、運算是 分開計費 的維度，估算成本時要分項看，不能只看月費。

什麼情境適合用 Supabase？

✅ 適合的場景

❌ 不適合的場景

Supabase vs Firebase

實戰範例

範例 1：用 supabase-js 連線與查詢

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

// anon key 是公開金鑰，安全靠 RLS 把關（絕不要把 service_role key 放前端）
const supabase = createClient(
  "https://xxxx.supabase.co",
  "公開的-anon-key"
);

// 查詢（實際能讀到哪些列，由 RLS 決定）
const { data, error } = await supabase
  .from("posts")
  .select("id, title, author")
  .eq("published", true);

// 新增
await supabase.from("posts").insert({ title: "Hello", author: "Alice" });

範例 2：認證（email 註冊 / 登入）

// 註冊
await supabase.auth.signUp({ email: "a@example.com", password: "secret" });

// 登入（成功後 SDK 自動帶 JWT，後續查詢會套用該使用者的 RLS）
await supabase.auth.signInWithPassword({
  email: "a@example.com",
  password: "secret",
});

// OAuth 第三方登入
await supabase.auth.signInWithOAuth({ provider: "github" });

範例 3：即時訂閱資料變更

// 監聽 messages 表的新增事件，即時推到前端
const channel = supabase
  .channel("room1")
  .on(
    "postgres_changes",
    { event: "INSERT", schema: "public", table: "messages" },
    (payload) => {
      console.log("新訊息：", payload.new);
    }
  )
  .subscribe();

範例 4：上傳檔案到 Storage

// 上傳到 avatars bucket（能不能上傳由該 bucket 的 RLS 政策決定）
await supabase.storage
  .from("avatars")
  .upload(`public/${userId}.png`, file);

// 取得公開 URL
const { data } = supabase.storage
  .from("avatars")
  .getPublicUrl(`public/${userId}.png`);

範例 5：serverless 連線字串（用交易模式連線池）

# 直連（長壽命伺服器用）
postgresql://postgres:[PWD]@db.xxxx.supabase.co:5432/postgres

# Supavisor 交易模式（serverless 用，連線埠通常為 6543）
postgresql://postgres.xxxx:[PWD]@aws-region.pooler.supabase.com:6543/postgres

最佳實踐

1. 每張表都要明確設定 RLS

ALTER TABLE my_table ENABLE ROW LEVEL SECURITY;
-- 然後針對 SELECT / INSERT / UPDATE / DELETE 各寫政策

上線前逐表檢查，避免「忘了開 RLS = 全公開」的事故。

2. 區分 anon key 與 service_role key

• anon key：公開，可放前端，安全完全靠 RLS
• service_role key：繞過 RLS，只能放在伺服器端 / Edge Function，絕不可外洩到前端

3. Serverless 用連線池（交易模式）

短命、大量並行的環境連 Supavisor 的交易模式埠，避免直連把 Postgres 連線數打爆。

4. 善用底層就是 Postgres 這件事

直接寫 SQL、建索引、用 pgvector / postgis、跑 migration——不要因為有 SDK 就放棄 Postgres 的全部能力。

5. 把商業敏感邏輯放伺服器端

需要繞過 RLS 或藏密鑰的邏輯，放 Edge Function / 後端，用 service_role 執行，不要塞前端。

常見問題

Q1：Supabase 跟 Firebase 最大的差別？

A：核心資料庫不同。Supabase 是 Postgres（關聯式 + 完整 SQL）且開源可自架；Firebase 是 Firestore（NoSQL）且封閉託管。要 JOIN、交易、避免鎖定 → Supabase；要 Google 生態深度整合、天生文件模型 → Firebase。

Q2：前端直接連資料庫，安全嗎？

A：安全的前提是 正確設定 RLS。前端用 anon key，能讀寫哪些資料列完全由資料庫層級的 RLS 政策決定。沒設好 RLS 就會出事，這是 Supabase 最關鍵的安全環節。

Q3：anon key 公開在前端不會有問題嗎？

A：anon key 本來就設計成公開的，它本身不給權限——權限由 RLS 控制。真正不能外洩的是 service_role key（它會繞過 RLS）。

Q4：serverless 連 Supabase 為什麼要用連線池？

A：Postgres 連線數有限且每條吃記憶體。serverless 大量短命實例若直連會爆連線。用 Supavisor 連線池（交易模式）把短命連線收斂成少量複用的實體連線。

Q5：可以自己架（self-host）嗎？

A：可以。Supabase 全部元件開源，能自架整套。代價是要自己承擔運維（升級、備份、擴容、監控），多數團隊仍選託管雲省事。

Q6：底層既然是 Postgres，能用一般 Postgres 工具嗎？

A：能。可用 psql、任何 Postgres client、ORM、migration 工具、擴充套件。這正是「不被鎖定」的好處——必要時也能把資料整個遷到別的 Postgres。

總結

核心要點

Supabase = 開源的 Firebase 替代方案，核心是 Postgres

  ├─ Database：完整 Postgres（SQL、擴充、pgvector）
  ├─ Auth：使用者認證 + JWT，整合 RLS
  ├─ Storage：S3 相容檔案儲存（也受 RLS 管）
  ├─ Realtime：WebSocket（資料變更 / 廣播 / Presence）
  ├─ 自動 API：PostgREST（REST）+ pg_graphql（GraphQL）
  └─ Edge Functions：Deno 邊緣函數

安全核心：RLS —— 授權邏輯下沉到資料庫，前端直連也安全
連線：直連（長壽命）vs Supavisor 連線池（serverless 用交易模式）

選用決策

要不要用 Supabase？
├─ 想要關聯式 + SQL + 開源不鎖定 → ✅ 很適合
├─ 想快速做全端 MVP（Auth/API/即時一次到位）→ ✅ 很適合
├─ 資料天生是文件、要 Google 生態 → 考慮 Firebase
└─ 只需要一個單純的 DB → 平台功能過剩

快速參考

記憶口訣

Supabase 三個關鍵字：

1. Postgres — 一切建立在標準 Postgres 上，開源不鎖定
2. RLS — 授權下沉到資料庫，前端直連也安全
3. 全包 — Auth / API / Storage / Realtime / Functions 一次到位

建立日期：2026-06-08 最後更新：2026-06-08