Supabase CLI 是開發者在本地環境中管理 Supabase 專案的強大工具。透過 CLI，你可以在本地建立完整的 Supabase 開發環境，包括資料庫、API、身份驗證等功能，讓開發過程更加順暢且高效。

為什麼需要 Supabase CLI？

在傳統的開發流程中，開發者通常需要直接在雲端環境進行開發和測試，這不僅增加了成本，也讓開發過程變得複雜。Supabase CLI 解決了這些問題：

• 離線開發：無需網路連線即可進行開發
• 快速迭代：本地環境啟動快速，測試更有效率
• 版本控制：資料庫結構和配置可以版本化管理
• 團隊協作：統一的開發環境確保團隊一致性

簡單來說：

像主角在自己房間昇級，CLI 幫你在本地模擬完整的 Supabase 後端（資料庫、認證、函式等），不必每次都跑到遠方（雲端）打怪，等到時機成熟再到雲端上戰場。

1. 安裝 Supabase CLI

使用 Homebrew（macOS）

brew install supabase/tap/supabase

驗證安裝

安裝完成後，執行以下指令確認安裝成功：

supabase --version

2. 初始設定與登入

登入 Supabase

首次使用需要登入你的 Supabase 帳號：

supabase login

這會開啟瀏覽器進行身份驗證，完成後會在本地儲存存取權杖。

登出

如需登出：

supabase logout

3. 專案初始化

建立新專案

在你的專案目錄中初始化 Supabase：

supabase init

這會建立以下檔案結構：

your-project/
├── supabase/
│   ├── config.toml          # 專案配置檔
│   └── migrations/         # 資料庫遷移檔案
└── .gitignore              # Git 忽略檔案

連結現有專案

如果你已經有 Supabase 雲端專案，可以連結到本地：

supabase link --project-ref your-project-id

4. 設定檔詳解（config.toml）

supabase/config.toml 是 CLI 的核心配置檔，包含所有服務的設定：

基本專案設定

# 專案基本資訊
project_id = "your-project-id"

[api]
enabled = true
port = 54321
schemas = ["public", "graphql_public"]
extra_search_path = ["public", "extensions"]
max_rows = 1000

[db]
port = 54322
shadow_port = 54320
major_version = 15

身份驗證設定

[auth]
enabled = true
port = 54324
site_url = "http://localhost:3000"
additional_redirect_urls = ["https://localhost:3000"]
jwt_expiry = 3600
refresh_token_rotation_enabled = true
security_update_password_require_reauthentication = true

[auth.email]
enable_signup = true
double_confirm_changes = true
enable_confirmations = false

[auth.sms]
enable_signup = true
enable_confirmations = false

儲存服務設定

[storage]
enabled = true
port = 54325
file_size_limit = "50MiB"

即時功能設定

[realtime]
enabled = true
port = 54323

Edge Functions 設定

[functions]
enabled = true
port = 54326

分析設定

[analytics]
enabled = false
port = 54327
gcp_project_id = ""
gcp_project_number = ""
gcp_jwt_path = "supabase/gcloud.json"

5. 基本 CLI 指令

啟動本地開發環境

supabase start

這個指令會：

• 啟動 PostgreSQL 資料庫
• 啟動 PostgREST API 服務
• 啟動 GoTrue 身份驗證服務
• 啟動 Realtime 服務
• 啟動 Storage 服務
• 啟動 Edge Functions 運行時

啟動後會顯示各服務的連接資訊：

Started supabase local development setup.

         API URL: http://localhost:54321
     GraphQL URL: http://localhost:54321/graphql/v1
          DB URL: postgresql://postgres:postgres@localhost:54322/postgres
      Studio URL: http://localhost:54323
    Inbucket URL: http://localhost:54324
      JWT secret: your-jwt-secret
        anon key: your-anon-key
service_role key: your-service-role-key

停止本地環境

supabase stop

查看服務狀態

supabase status

重新啟動服務

supabase restart

查看日誌

由於較新版本的 CLI 沒有內建 logs 指令，可以使用 Docker 指令查看容器日誌：

# 查看所有 Supabase 相關容器
docker ps | grep supabase

# 查看特定服務日誌（以 API 為例）
docker logs supabase_kong_<project-name> -f

# 查看資料庫日誌
docker logs supabase_db_<project-name> -f

重置本地環境

完全重置本地資料庫和配置：

supabase db reset

6. 資料庫管理指令

套用遷移

supabase db push

從遠端同步結構到本地

supabase db pull

小結

Supabase CLI 為開發者提供了完整的本地開發環境，讓你可以在不依賴網路的情況下進行開發和測試。透過合適的配置和基本指令的掌握，你可以大幅提升開發效率。

在下集中，我們將深入探討如何進行資料庫更新、資料填充，以及更進階的 CLI 使用技巧。

... to be continued

有任何想討論歡迎留言，或需要指正的地方請鞭大力一點，歡迎訂閱、按讚加分享，分享給想要提升開發效率的朋友