Supabase CLI 参考文档

原创于 2026-09-13 10:58:37 发布 · 97 阅读

本内容遵循CC 4.0 BY-SA版权协议

Supabase CLI 参考文档

Supabase CLI 将 Supabase 平台带到你的终端：本地跑全套开发栈、管理数据库迁移、部署 Edge Functions、生成类型、自动化项目工作流。本文基于官方 supabase.com/llms/cli.txt 全文整理。

一、概述

Supabase CLI 提供在本地开发项目并部署到 Supabase 平台所需的全部工具。CLI 仍在持续开发中，但已包含与 Supabase 项目和平台协作的所有核心功能。

能力	命令
本地运行 Supabase	`supabase init` + `supabase start`
管理数据库迁移	`supabase migration`
CI/CD 发布生产	`supabase db push`
管理项目	`supabase projects`
从数据库结构生成类型	`supabase gen types`
Shell 自动补全	`supabase completion`

源码：https://github.com/supabase/cli（MIT 协议，pnpm monorepo）

二、安装

# YOLO 一键脚本
curl -fsSL https://raw.githubusercontent.com/supabase/cli/main/install | bash

# npm（推荐作为项目依赖）
npm install -D supabase        # 或 bun/pnpm/yarn add -D supabase
npm install -D supabase@beta   # beta 通道

# macOS（Homebrew）
brew install supabase/tap/supabase      # 始终最新
brew install supabase                    # 官方 formula，可能滞后
brew install supabase/tap/supabase-beta  # beta 通道

# Windows（Scoop）
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase
scoop install supabase-beta              # beta 通道

Linux：从 GitHub Releases 下载 .apk、.deb、.rpm 或 .pkg.tar.zst
社区维护：pkgx、Nixpkgs

安装后可通过 supabase --help 或 supabase <命令> --help 查看所有命令、flags 和示例。

三、全局标志与环境变量

全局标志

所有命令均支持全局标志（global flags），如 --help、--version 等。

常用环境变量

变量	作用
`SUPABASE_WORKDIR`	覆盖工作目录（等价于 `--workdir` 标志）
`SUPABASE_ACCESS_TOKEN`	CI 环境下跳过 `login`，直接提供访问令牌
`SUPABASE_DB_PASSWORD`	CI 环境下跳过数据库密码提示
`SUPABASE_SERVICES_HOSTNAME`	容器内运行 CLI 时，指向可达的服务主机名（如 `host.docker.internal`）

四、通用命令

`supabase bootstrap [template]`

从入门模板引导一个 Supabase 项目。

`supabase init`

初始化本地项目，在当前目录创建 supabase/config.toml。

supabase init [flags]

配置针对每个本地项目
supabase 目录还包含 migrations、functions、tests 等对象

`supabase login`

使用 personal access token 认证，连接 CLI 到你的 Supabase 账户。

Token 安全存储在系统原生凭据库中；不可用时写入 ~/.supabase/access-token 明文文件
CLI 使用该 token 访问 Management API（项目、函数、密钥等）

`supabase link`

将本地项目链接到托管的 Supabase 项目。

supabase link [flags]   # 常用：--project-ref <ref>

从平台获取 PostgREST 配置并与本地配置文件校验
db dump、db push、db pull 等命令需要先 link
项目 ref 可在 Dashboard URL 中获取：https://supabase.com/dashboard/project/<ref>

`supabase start`

启动 Supabase 本地开发栈（所有服务容器默认启动）。

supabase start [flags]
# -x gotrue,imgproxy   排除不需要的容器
# --ignore-health-check  忽略健康检查错误

本地栈包含：Postgres、Auth、Realtime、Storage、Edge Functions 和 Supabase APIs
建议至少 7GB 内存 启动全部服务
首次运行需下载 Docker 镜像，耗时较长

`supabase stop`

停止本地 Supabase 容器（数据在重启间保留）。

supabase stop [flags]
# --no-backup   重置本地开发数据
# --all         停止机器上所有本地项目实例（配合 --no-backup 会删除所有本地项目数据，谨慎使用）

`supabase status`

显示本地栈状态。

supabase status [flags]
# -o env   导出 supabase-js 初始化连接参数（JWT_SECRET、ANON_KEY、SERVICE_ROLE_KEY）

五、数据库命令

`supabase db pull [migration name]`

从远程数据库拉取 schema 变更，在 supabase/migrations 下新建迁移文件。

需要先 supabase link；自托管数据库可用 --db-url 传连接参数
需要 Docker（会启动本地 Postgres 容器来 diff 远程 schema）
无迁移历史时用 pg_dump 抓全量；否则仅 diff schema 变更
--diff-engine pg-delta / --use-pg-delta：切换 pg-delta diff 引擎

`supabase db push`

推送所有本地迁移到远程数据库。

supabase db push [flags]   # --dry-run 先预览变更列表

首次运行创建 supabase_migrations.schema_migrations 迁移历史表
已应用的迁移自动跳过；历史表异常用 migration repair 修复

`supabase db reset`

将本地数据库重置为当前迁移状态。

supabase db reset [flags]
# --linked   销毁链接的远程数据库并从本地迁移重建（破坏性操作，仅限 dev/staging）
# --db-url   指定自托管数据库

重建本地 Postgres 容器并应用 supabase/migrations 全部迁移
定义在 supabase/seed.sql 的测试数据在迁移后写入
本地开发期间的其他数据和 schema 变更会被丢弃
远程 reset 不删除自定义角色（Postgres 角色是集群级实体）

`supabase db dump`

从远程数据库导出内容，运行 pg_dump（排除 Supabase 托管 schema：auth、storage 及扩展创建的）。

supabase db dump [flags]
# --data-only   仅导出数据
# --role-only   仅导出角色
# --db-url      自托管连接

权限迁移提示：恢复到新项目时表会继承目标库的默认权限。如需保留特定权限，恢复前先执行：

ALTER DEFAULT PRIVILEGES IN SCHEMA public REVOKE ALL ON TABLES FROM anon, authenticated;

`supabase db diff`

对比本地或远程数据库的 schema 变更。

supabase db diff [flags]
# --linked       对比远程库
# --db-url       对比自托管库
# -f             将 diff 保存为新迁移文件
# --schema public,extensions   限定对比的 schema 子集

基于 djrobstep/migra，将目标库与影子库（按本地迁移构建）对比
已知失败场景：publication 变更、storage buckets 变更、带 security_invoker 属性的视图

`supabase db lint`

检查本地数据库 schema 错误（运行 plpgsql_check）。

supabase db lint [flags]
# --level warning|error     默认 warning
# --schema                  限定 schema
# --fail-on none|warning|error   控制非零退出码（CI/CD 中很有用）

`supabase db start`

仅启动本地 Postgres 数据库（不需要完整栈时）。

六、迁移命令

`supabase migration new <name>`

创建空的迁移文件（supabase/migrations/<timestamp>_<name>.sql）。

其他命令（如 db diff）的输出可通过 stdin 管道到该命令

`supabase migration list`

列出本地和远程的迁移历史（需要先 link）。

本地：supabase/migrations 目录；远程：supabase_migrations.schema_migrations 表
仅比较时间戳识别差异；不一致时用 migration repair 修复

`supabase migration fetch`

从历史表获取迁移文件。

`supabase migration repair [version] ...`

修复远程迁移历史表。

supabase migration repair <timestamp> --status applied    # 插入记录
supabase migration repair <timestamp> --status reverted  # 删除记录

典型流程示例：

$ supabase migration list
 LOCAL │ REMOTE │ TIME (UTC)
 ──────┼────────┼──────────────
       │ 20230103054303 │ 2023-01-03 05:43:03
 20230103054315 │       │ 2023-01-03 05:43:15

# 删除多余本地文件 → 标记远程迁移为 reverted → 重新 db pull
$ rm supabase/migrations/20230103054315_remote_commit.sql
$ supabase migration repair 20230103054303 --status reverted

`supabase migration squash`

将本地 schema 迁移压缩为单个迁移文件。

等价于应用现有迁移后做 schema-only dump
限制：数据操作语句（insert/update/delete）会被省略，需手动补回——包括 cron jobs、storage buckets、vault 加密密钥
默认更新最新的 <timestamp>_<name>.sql，可用 --version <timestamp> 覆盖
目录为空时无操作

`supabase migration up`

将待应用的迁移应用到本地数据库。

`supabase migration down`

将已应用的迁移回滚到最后 n 个版本。

七、测试与类型生成

测试

supabase test db [path] ...   # 用 pgTAP 测试本地数据库（每个测试在独立事务中回滚）
supabase test new <name>      # 创建新测试文件（.sql 或 .pg 后缀，位于 supabase/tests）

类型生成

supabase gen types [flags]          # 从 Postgres schema 生成类型（默认 TypeScript，支持 Go、Swift）
supabase gen types --local          # 从本地数据库生成
supabase gen types --linked         # 从链接项目生成
supabase gen signing-key [flags]    # 生成 JWT 签名私钥

类型生成连接数据库，生成匹配表、视图、存储过程的类型定义，并尊重关系、约束和自定义类型。

支持算法：ES256（ECDSA P-256，推荐）、RS256（RSA）
社区支持的 GitHub Action 可自动生成 TypeScript 类型

八、种子与检查

种子

supabase seed buckets    # 种子化 config.toml [storage.buckets] 声明的存储桶

检查（inspect）

命令	作用
`supabase inspect db bloat`	估算表膨胀（dead tuples 导致的 bloat 及浪费空间）
`supabase inspect db blocking`	显示持锁阻塞的语句与被阻塞语句
`supabase inspect db calls`	按调用次数排序的热门查询（pg_stat_statements）
`supabase inspect db db-stats`	缓存命中率、总大小、WAL 大小等统计
`supabase inspect db index-stats`	索引大小、使用率、扫描数、未使用状态
`supabase inspect db locks`	已对关系加排他锁的查询
`supabase inspect db long-running-queries`	运行超过 5 分钟的查询
`supabase inspect db outliers`	按总执行时间排序的查询（含 I/O 时间）
`supabase inspect db replication-slots`	逻辑复制槽信息（状态、客户端地址、滞后量 GB）
`supabase inspect db role-stats`	数据库角色信息
`supabase inspect db table-stats`	表大小、索引大小、估算行数
`supabase inspect db traffic-profile`	表读写活动比例（Read-Heavy / Write-Heavy / Balanced 分类）
`supabase inspect db vacuum-stats`	每表 vacuum 操作统计
`supabase inspect report [flags]`	为所有 inspect 命令生成 CSV 输出

九、组织与项目管理

组织

supabase orgs create     # 创建组织
supabase orgs list       # 列出当前用户所属组织

项目

supabase projects create [项目名] [flags]   # 创建项目
supabase projects list                      # 列出可访问的项目
supabase projects api-keys [flags]          # 列出项目 API keys
supabase projects delete [ref]              # 删除项目

CLI 项目管理适合自动化脚本和可重复的环境供给（无需 Dashboard）。

预览分支

supabase branches create [name] [flags]   # 创建预览分支
supabase branches list                    # 列出所有预览分支
supabase branches get [name]              # 获取分支详情
supabase branches update [name] [flags]   # 更新分支
supabase branches pause [name]            # 暂停分支
supabase branches unpause [name]          # 恢复分支
supabase branches delete [name]           # 删除分支

配置

supabase config push    # 将本地 config.toml 推送到链接项目（配置即代码）

十、Edge Functions

Edge Functions 是无服务器函数，运行在靠近用户的位置，用 TypeScript 编写、运行在 Deno 兼容的 edge runtime 上——无包管理、冷启动快、内置安全。适合处理 webhooks、自定义 API 端点、数据校验、个性化内容。

supabase functions new <Function name>        # 本地创建函数（生成 index.ts 样板）
supabase functions list [flags]               # 列出链接项目的函数
supabase functions download [Function name]   # 下载函数源码（不指定名称则下载全部）
supabase functions serve [flags]              # 本地运行所有函数
supabase functions deploy [Function name]     # 部署函数到链接项目
supabase functions delete <Function name>     # 从项目删除函数（不影响本地）

调试（serve 的 inspector 标志）

supabase functions serve --inspect                     # 等价于 --inspect-mode brk
supabase functions serve --inspect-mode run|brk|wait   # run: 允许连接；brk: 首行断点；wait: 等待 inspector 连接
supabase functions serve --inspect-main                # 允许主 worker 的 inspector 会话

config.toml edge_runtime 段可配置：

inspector_port：Inspector 监听端口（默认 8083）
policy：per_worker（多个请求转发给已创建的 worker）/ oneshot（单请求后退出，调试用）

十一、密钥与存储

Secrets

supabase secrets set <NAME=VALUE> ...   # 设置密钥（可多个，或从 .env 加载）
supabase secrets list                   # 列出所有密钥
supabase secrets unset [NAME] ...       # 取消密钥

密钥安全存储并作为环境变量提供给 Edge Functions。

Storage

supabase storage ls [path]       # 按路径前缀列出对象
supabase storage cp <src> <dst>  # 复制对象
supabase storage mv <src> <dst>  # 移动对象
supabase storage rm <file> ...   # 删除对象

十二、认证与域

SSO（Single Sign-On）

supabase sso add [flags]                  # 添加 SSO 身份提供商
supabase sso list                         # 列出所有 SSO 连接
supabase sso show <provider-id> [flags]   # 显示提供商信息（--metadata 获取原始 SAML XML）
supabase sso info                         # 返回项目注册所需的 SAML SSO 设置
supabase sso update <provider-id> [flags] # 更新提供商配置
supabase sso remove <provider-id>         # 移除提供商（会阻止现有用户登录，谨慎）

自定义域名

supabase domains create [flags]    # 创建自定义主机名（需 CNAME 指向项目子域）
supabase domains activate          # 激活（激活后第三方 auth 提供商在 Supabase 子域上失效）
supabase domains get               # 获取当前配置
supabase domains reverify          # 重新验证配置
supabase domains delete            # 删除配置

自定义域名与 vanity 子域名互斥。

Vanity 子域名

supabase vanity-subdomains activate [flags]          # 激活 vanity 子域名
supabase vanity-subdomains get                       # 获取当前子域名
supabase vanity-subdomains check-availability [flags] # 检查可用性
supabase vanity-subdomains delete                    # 删除（回退到 project-ref 路由）

十三、网络与安全

# 网络封禁（IP 被临时封禁的流量模式）
supabase network-bans get          # 查看当前封禁
supabase network-bans remove [flags] # 解除封禁

# 网络限制
supabase network-restrictions get     # 获取当前限制
supabase network-restrictions update [flags]  # 更新限制

# SSL 强制
supabase ssl-enforcement get    # 获取当前 SSL 配置
supabase ssl-enforcement update [flags]  # 更新 SSL 配置

# Postgres 配置
supabase postgres-config get         # 获取当前配置覆盖
supabase postgres-config update [flags]  # 更新（可能影响稳定性，谨慎）
supabase postgres-config delete [flags]  # 删除指定覆盖，恢复默认值

十四、其他命令

supabase snippets list                    # 列出链接项目的 SQL snippets
supabase snippets download <snippet-id>   # 下载 snippet 内容
supabase services                         # 显示所有 Supabase 服务版本

Shell 自动补全

# bash
source <(supabase completion bash)        # Linux: 写入 /etc/bash_completion.d/supabase

# zsh
source <(supabase completion zsh)         # macOS: 写入 $(brew --prefix)/share/zsh/site-functions/_supabase

# fish
supabase completion fish | source         # 写入 ~/.config/fish/completions/supabase.fish

# powershell
supabase completion powershell | Out-String | Invoke-Expression

另有社区支持的 Fig autocomplete spec（macOS 终端）。

Telemetry

supabase telemetry 管理 CLI 遥测设置。

十五、典型工作流示例

工作流 1：本地开发

supabase init          # 创建 ./supabase/config.toml
supabase start         # 启动本地栈（Postgres/Auth/Realtime/Storage/Functions）
supabase status        # 查看状态与连接参数

工作流 2：迁移管理

supabase migration new create_profiles   # 新建迁移
supabase db diff                         # 对比本地 schema 变更
supabase db push                         # 推送迁移到远程
supabase db reset                        # 重置本地库

工作流 3：连接远程项目

supabase login
supabase link --project-ref $PROJECT_ID
supabase gen types --linked   # 生成远程 schema 的 TS 类型

工作流 4：Edge Functions

supabase functions new hello-world
supabase functions serve      # 本地测试
supabase functions deploy hello-world   # 部署

工作流 5：CI/CD

# CI 环境跳过交互式登录
export SUPABASE_ACCESS_TOKEN=${{ secrets.SUPABASE_ACCESS_TOKEN }}
export SUPABASE_DB_PASSWORD=${{ secrets.SUPABASE_DB_PASSWORD }}
supabase db push --dry-run    # 预览
supabase db lint --fail-on error   # 失败即阻断构建