Supabase CLI 权威中文参考手册

前言

Supabase 命令行界面（CLI）是 Supabase 生态系统中一款功能强大的工具，旨在简化本地开发流程并高效管理您的 Supabase 平台项目。它使开发人员能够在本地环境中完整地运行 Supabase 服务栈，包括 Postgres 数据库、身份验证、边缘函数等，从而实现快速迭代和测试，而无需持续依赖云端资源。通过 CLI，您可以管理数据库迁移、部署无服务器函数、处理项目配置，并以可重复、可编程的方式与 Supabase 平台进行交互。

本手册旨在为中文开发者社区提供一份详尽、准确且易于理解的 Supabase CLI 参考指南。无论您是初次接触 Supabase 的新手，还是希望将 CLI 深度集成到 CI/CD 流程中的资深开发者，本手册都将为您提供从入门到精通所需的全方位知识。我们将系统地介绍每一个命令，阐明其用途、语法、参数和选项，并通过实例展示其在实际工作流中的应用。本手册严格按照官方文档的侧边栏结构进行组织，确保您能够快速定位并掌握所需的功能。

---

第一章：入门与核心工作流

本章将引导您完成使用 Supabase CLI 的基础设置和核心操作。掌握这些基本命令是进行任何本地开发或项目管理的前提。这些命令并非孤立存在，而是构成了一个逻辑清晰、循序渐进的核心工作流。理解这个工作流的顺序至关重要：首先，您需要在本地初始化一个项目配置 (init)；接着，为了与云端平台交互，您必须登录您的 Supabase 账户 (login)；然后，将您的本地项目与一个托管在 Supabase 平台上的远程项目进行关联 (link)；最后，启动本地开发所需的所有服务 (start)。遵循这一流程将确保您能够顺利地搭建起开发环境，避免常见的配置错误。

1.1 全局选项

全局选项（Global Flags）是可应用于几乎所有 Supabase CLI 命令的通用参数，用于修改命令的全局行为。熟悉这些选项可以帮助您更灵活地控制 CLI 的输出、调试过程和工作目录。

选项 (Flag)	描述
--create-ticket	当 CLI 发生任何错误时，自动创建一个支持工单。
--debug	将详细的调试日志输出到标准错误流（stderr），用于问题排查。
--dns-resolver \<[ native https ]\>	指定用于域名解析的解析器。
--experimental	启用实验性功能。这些功能可能尚不稳定或未来可能发生变化。
-h, --help	显示 supabase 命令或其子命令的帮助信息。
--network-id <string>	使用指定的 Docker 网络，而不是由 CLI 自动生成的网络。
-o, --output <[ env pretty json toml yaml ]>	设置状态变量的输出格式，例如 supabase status 命令的输出。
--profile <string>	使用特定的配置文件连接到 Supabase API。
--workdir <string>	指定 Supabase 项目目录的路径，覆盖默认的当前目录。
--yes	对所有交互式提示自动回答"是"。

1.2 supabase init - 初始化本地项目

supabase init 命令是您在本地开始一个新 Supabase 项目的起点。它负责创建本地开发所需的基本配置文件和目录结构 1。

用途

此命令用于初始化 Supabase 本地开发的配置。执行后，它会在当前工作目录下创建一个 supabase 文件夹，并在其中生成一个核心配置文件 config.toml。这个配置文件包含了项目的各项设置，是后续所有本地开发命令的基础 1。

语法

supabase init [flags]

选项 (Flags)

选项	描述
--force	如果 supabase/config.toml 文件已存在，此选项将强制覆盖它 1。
--use-orioledb	使用 OrioleDB 存储引擎替代标准的 Postgres 1。
--with-intellij-settings	为 Deno 生成适用于 IntelliJ IDEA 的项目设置 2。
--with-vscode-settings	为 Deno 生成适用于 VS Code 的项目设置 1。

示例

要初始化一个新项目，只需在项目根目录下运行：

supabase init

执行此命令后，您的项目目录中将出现一个 supabase 目录，其中至少包含 config.toml 文件。随着项目的开发，此目录还将包含 migrations（数据库迁移）、functions（边缘函数）和 tests（测试）等子目录 1。

1.3 supabase login - 登录 Supabase 账户

在执行任何需要与 Supabase 云平台交互的命令（如关联项目、部署函数等）之前，您必须通过 supabase login 命令进行身份验证 3。

用途

此命令通过您的个人访问令牌（Personal Access Token）将 Supabase CLI 连接到您的 Supabase 账户。成功登录后，访问令牌会被安全地存储在您操作系统的原生凭据存储系统中（如 macOS 的 Keychain 或 Windows 的 Credential Manager）。如果原生存储不可用，令牌将以纯文本形式保存在 ~/.supabase/access-token 文件中。CLI 将使用此令牌来访问管理 API，以执行项目、函数和密钥等操作 3。

在 CI/CD 等自动化环境中，您可以通过设置 SUPABASE_ACCESS_TOKEN 环境变量来跳过交互式登录流程 3。

语法

supabase login [flags]

选项 (Flags)

选项	描述
--name <string>	（可选）为存储的令牌指定一个名称 3。
--no-browser	（可选）不自动在浏览器中打开登录流程页面 4。
--token <string>	（可选）直接提供一个访问令牌，而不是通过自动登录流程获取 3。

示例

运行以下命令以开始登录过程：

supabase login

CLI 将提示您访问 Supabase 仪表盘的个人访问令牌页面，并要求您输入一个新生成的令牌。

您可以从 https://supabase.com/dashboard/account/tokens 生成一个访问令牌
输入您的访问令牌: sbp_**********************************
supabase 登录完成。

1.4 supabase link - 关联远程项目

初始化本地项目并登录后，下一步是使用 supabase link 命令将您的本地开发环境与一个已托管在 Supabase 平台上的远程项目进行关联。

用途

此命令在本地配置文件和远程 Supabase 项目之间建立连接。它会从云端获取 PostgREST 等服务的配置，并与本地 config.toml 文件进行验证。如果提供了数据库密码，它还会验证数据库连接设置，并将密码安全地存储在本地。许多关键命令，如 db dump、db push 和 db pull，都要求项目必须首先被关联。

语法

supabase link [flags]

选项 (Flags)

选项	描述
-p, --password <string>	（可选）提供远程 Postgres 数据库的密码。如果未提供，将在执行时提示输入 5。
--project-ref <string>	（必选）指定要关联的 Supabase 项目的引用 ID（Project ref）。您可以在项目仪表盘的 URL 或项目设置中找到它 5。

示例

使用您的项目引用 ID 关联项目：

supabase link --project-ref your-project-ref-goes-here

执行后，CLI 会请求输入数据库密码（可以留空跳过），然后确认关联完成 5。

输入您的数据库密码 (或留空跳过): ********
supabase 关联完成。

在 CI/CD 环境中，为了避免交互式提示，建议通过 SUPABASE_DB_PASSWORD 环境变量提供数据库密码。

1.5 supabase start - 启动本地开发环境

完成初始化、登录和关联后，您就可以使用 supabase start 命令在本地启动完整的 Supabase 服务栈了。

用途

此命令会根据 supabase/config.toml 文件的配置，使用 Docker 启动所有 Supabase 核心服务的容器，包括 Postgres 数据库、GoTrue 身份验证、Realtime 实时服务、Storage API 等。这为您提供了一个功能齐全且与云端环境高度一致的本地开发环境。

语法

supabase start [flags]

选项 (Flags)

选项	描述
-x, --exclude <strings>	（可选）指定一个或多个不希望启动的服务容器名称，多个名称以逗号分隔。可用的服务包括 [gotrue, realtime, storage-api, imgproxy, kong, mailpit, postgrest, postgres-meta, studio, edge-runtime, logflare, vector, supavisor] 6。
--ignore-health-check	（可选）忽略对服务健康状况的检查。即使有服务不健康，命令也会以成功状态（退出码 0）结束 6。

示例

要启动所有服务，只需运行：

supabase start

成功启动后，CLI 会应用本地的数据库迁移和种子数据，并显示启动成功的消息。

创建自定义角色 supabase/roles.sql...
应用迁移 20220810154536_employee.sql...
填充数据 supabase/seed.sql...
已启动 supabase 本地开发环境。

请注意，启动所有服务建议至少有 7GB 的可用内存。

1.6 supabase stop - 停止本地开发环境

开发工作完成后，您可以使用 supabase stop 命令来安全地关闭所有正在运行的本地 Supabase 服务。

用途

此命令会停止并移除由 supabase start 创建的所有 Docker 容器，释放系统资源。这是一个良好的实践，可以确保在不进行开发时，系统保持整洁。

语法

supabase stop [flags]

选项 (Flags)

（此命令通常不与特定选项一起使用，但支持全局选项。）

示例

supabase stop

执行后，所有相关的 Docker 容器将被停止。

1.7 supabase status - 查看本地环境状态

在本地开发环境运行期间，您可以使用 supabase status 命令来检查其状态并获取关键的连接信息 7。

用途

此命令显示本地 Supabase 服务栈的运行状态。如果服务正在运行，它会列出所有关键服务的访问 URL、数据库连接字符串以及用于本地开发的 API 密钥和 JWT 密钥。这对于配置您的前端应用程序或客户端库以连接到本地 Supabase 实例至关重要 7。

语法

supabase status [flags]

选项 (Flags)

选项	描述
--override-name <strings>	（可选）覆盖特定的变量名称 7。

示例

运行 supabase status 将显示如下信息：

supabase status

响应示例

supabase 本地开发环境正在运行。

API URL: http://127.0.0.1:54321
GraphQL URL: http://127.0.0.1:54321/graphql/v1
DB URL: postgresql://postgres:postgres@127.0.0.1:54322/postgres
Studio URL: http://127.0.0.1:54323
Inbucket URL: http://127.0.0.1:54324
JWT secret: super-secret-jwt-token-with-at-least-32-characters-long
anon key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
service_role key: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

这些信息可以直接用于初始化 supabase-js 客户端库，以便在本地进行开发和测试 7。

---

第二章：数据库管理

数据库是任何 Supabase 项目的核心。Supabase CLI 提供了一套强大而全面的工具来管理数据库的生命周期，从模式设计、迁移、数据填充到审查和维护。本章将详细介绍这些命令，并重点阐述如何利用它们构建一个类似于 Git 的、版本化的数据库管理工作流。这种方法论将数据库的变更视为代码，通过迁移文件进行跟踪，从而实现可重复、可审查且安全的数据库部署。

这个工作流的核心在于 db diff、migration new 和 db push 三个命令的协同作用。当您在本地数据库中通过 Supabase Studio 或其他工具进行模式更改后，supabase db diff 会自动检测这些更改并生成相应的 SQL 语句。然后，您可以将这些 SQL 语句通过管道传递给 supabase migration new，创建一个带有时间戳的、版本化的迁移文件。这个文件可以像其他代码一样提交到版本控制系统（如 Git）中。最后，当您准备将这些更改部署到生产环境时，supabase db push 命令会读取这些迁移文件，并按顺序将它们应用到远程数据库上。这个流程确保了数据库模式的演进是有序、可控且透明的。

2.1 数据库命令 (db)

supabase db 命令组是进行数据库直接操作的主要入口，涵盖了从启动、重置到模式比对和检查的各种功能。

supabase db start - 仅启动本地数据库

此命令是 supabase start 的一个变体，专门用于仅启动本地 Postgres 数据库容器，而不启动其他 Supabase 服务（如 GoTrue, Realtime 等）。这在您只需要数据库本身进行工作时非常有用，可以节省系统资源 8。

语法

supabase db start [flags]

选项 (Flags)

选项	描述
--from-backup <string>	（可选）从一个逻辑备份文件路径启动并恢复数据库 8。

supabase db reset - 重置数据库

此命令用于将数据库重置到初始状态，并重新应用所有本地的迁移文件。它可以作用于本地数据库，也可以作用于已关联的远程项目。

用途

在开发过程中，当您想从一个干净的状态重新开始时，此命令非常有用。它会删除所有用户创建的表、视图和数据，然后按顺序执行 supabase/migrations 目录下的所有迁移文件，最后运行种子脚本（seed.sql）来填充初始数据。需要注意的是，由于 Postgres 的角色是集群级别的，此命令不会删除任何自定义角色 9。

语法

supabase db reset [flags]

选项 (Flags)

选项	描述
--db-url <string>	（可选）重置由连接字符串指定的数据库 9。
--last <uint>	（可选）仅重置到最后 n 个迁移版本 9。
--linked	（可选）重置已关联的远程项目 9。
--local	（可选）重置本地数据库（默认行为） 9。
--no-seed	（可选）重置后跳过运行种子脚本 9。
--version <string>	（可选）重置到指定的迁移版本 9。

supabase db dump - 转储数据库模式

此命令用于从数据库中导出其模式（schema），并保存为一个 SQL 文件。默认情况下，它只导出模式定义，不包含数据或角色。

用途

db dump 对于备份数据库结构、在不同环境间同步模式或将现有数据库集成到 Supabase 迁移工作流中非常关键。它会智能地排除 Supabase 自身管理的模式（如 auth, storage 等）。

语法

supabase db dump [flags]

选项 (Flags)

选项	描述
--data-only	仅转储数据记录，不转储模式 11。
--role-only	仅转储集群角色，不转储模式 11。
--db-url <string>	（可选）从指定的数据库连接字符串转储 11。
-f, --file <string>	（可选）指定保存转储内容的输出文件路径。默认为标准输出 11。
--linked	（可选）从已关联的远程项目转储 11。
--local	（可选）从本地数据库转储 11。
-s, --schema <strings>	（可选）指定要包含的模式列表，以逗号分隔 11。

示例

将远程数据库的模式转储到本地文件 supabase/schema.sql：

supabase db dump -f supabase/schema.sql

supabase db pull - 从远程拉取模式变更

此命令用于从远程数据库拉取模式变更。根据其名称推断，它的功能是检测远程数据库中存在但本地迁移文件中不存在的模式更改，并可能将这些更改生成为新的本地迁移文件。这对于多人协作或在 Supabase 仪表盘中直接修改了生产数据库模式后，将这些变更同步回本地开发环境的场景非常有用。

注意：现有文档对此命令的详细用法和选项描述较少。

supabase db push - 将迁移推送到远程数据库

此命令用于将所有本地尚未应用的迁移文件应用到远程数据库。

用途

这是将本地开发完成的数据库模式变更部署到生产或预演环境的关键步骤。它会连接到已关联的远程项目，检查 supabase_migrations.schema_migrations 历史表，并仅执行那些尚未在远程数据库上运行过的迁移文件 13。

语法

supabase db push [flags]

选项 (Flags)

选项	描述
--dry-run	打印将要应用的迁移列表，但实际上不执行它们。用于部署前的检查。
--include-roles	同时推送 supabase/roles.sql 文件中定义的自定义角色。
--include-seed	同时推送配置文件中指定的种子数据。
-p, --password <string>	（可选）提供远程数据库的密码。
--db-url <string>	（可选）推送到由连接字符串指定的数据库。

supabase db diff - 比对数据库模式差异

此命令用于比较不同数据库状态之间的模式差异，并生成相应的 SQL 变更脚本。

用途

这是实现版本化数据库工作流的核心工具。您可以比对本地数据库与本地迁移文件的状态，以捕捉您在本地所做的模式更改。也可以比对本地迁移文件与远程数据库，以验证部署是否一致。其输出可以直接用于创建新的迁移文件。

语法

supabase db diff [flags]

选项 (Flags)

选项	描述
-f, --file <string>	将比对出的模式差异保存为一个新的迁移文件，而不是打印到标准输出。
--linked	将本地迁移文件与已关联的远程项目进行比对 。
--local	将本地迁移文件与本地数据库进行比对（默认行为）。
-s, --schema <strings>	（可选）指定要比对的模式列表，以逗号分隔 。
--use-migra / --use-pg-schema / --use-pgadmin	（可选）选择不同的底层比对工具。

示例

检测本地数据库的模式变更，并创建一个名为 new_feature 的新迁移文件：

supabase db diff -f new_feature

supabase db lint - 检查数据库模式

此命令用于检查数据库模式中是否存在潜在的错误或不规范的写法 15。

用途

它利用 plpgsql_check 扩展来静态分析您的数据库函数和触发器，帮助您在部署前发现 bug。这对于维护高质量和健壮的数据库逻辑非常有帮助，尤其是在 CI/CD 流程中 15。

语法

supabase db lint [flags]

选项 (Flags)

| 选项 | 描述 |
|--------------------------|--------------------|------------------------------|-------------------------------------------|
| `--level <[ warning | error ]>` | 设置要报告的错误级别，默认为 warning 15。 |
| `--fail-on <[ none | warning | error ]>` | 设置导致命令以非零状态码退出的错误级别。用于 CI/CD 流程中的质量门禁 15。 |
| -s, --schema <strings> | （可选）指定要检查的模式列表 15。 |

2.2 迁移命令 (migration)

supabase migration 命令组专注于管理 supabase/migrations 目录下的迁移文件，提供了创建、列表、修复和应用迁移的完整功能。

supabase migration new - 创建新迁移

此命令用于在 supabase/migrations 目录下创建一个新的、带有时间戳前缀的 SQL 迁移文件 16。

语法

supabase migration new <migration_name>

参数

• <migration_name>: 迁移的描述性名称，将成为文件名的一部分。

示例

创建一个用于添加 users 表的迁移：

supabase migration new create_users_table

这将生成一个文件，如 supabase/migrations/20230306095710_create_users_table.sql。

supabase migration list - 列出迁移状态

此命令用于显示本地迁移文件与远程数据库中已应用迁移的历史记录，并进行比较。

用途

通过此命令，您可以清晰地看到哪些迁移仅存在于本地，哪些已成功部署到远程，帮助您跟踪部署状态。如果本地和远程历史记录不一致，可以使用 migration repair 命令进行修复。

语法

Bash

supabase migration list [flags]

supabase migration up - 应用待定迁移

此命令用于将所有待定的（即尚未在目标数据库上应用的）本地迁移文件应用到数据库。这通常用于在本地环境中手动应用新的迁移以进行测试。

语法

Bash

supabase migration up [flags]

supabase migration squash - 合并迁移

此命令将多个本地迁移文件合并成一个单一的迁移文件。合并后的文件内容等同于将所有现有迁移应用到本地数据库后，对其进行一次纯模式的转储（schema-only dump）。

用途

当项目历史悠久，积累了大量迁移文件时，此命令可以帮助清理和简化迁移历史。但需要注意，它会忽略所有数据操作语句（如 INSERT, UPDATE, DELETE），这些需要手动重新添加。

语法

supabase migration squash [flags]

supabase migration repair - 修复迁移历史

此命令用于手动修复远程数据库中的迁移历史表 (supabase_migrations.schema_migrations)，以解决本地与远程历史记录不一致的问题。

用途

当发生迁移失败、手动干预数据库或版本控制合并错误导致历史记录不同步时，可以使用此命令。您可以手动将某个迁移版本标记为 applied（已应用）或 reverted（已回滚）。

语法

supabase migration repair <version> --status <[ applied | reverted ]>

示例

将版本号为 20230103054303 的迁移标记为已回滚：

supabase migration repair 20230103054303 --status reverted

supabase migration fetch - 从历史记录获取迁移

此命令的功能是从远程数据库的迁移历史表中获取迁移文件。这在您丢失了本地迁移文件但远程数据库拥有完整历史记录的情况下非常有用，可以帮助您恢复本地的迁移目录 21。

2.3 数据填充 (seed) 与审查 (inspect)

supabase seed - 填充种子数据

Supabase CLI 支持通过一个 supabase/seed.sql 文件来为您的数据库填充初始数据或测试数据。当您运行 supabase start 或 supabase db reset 时，这个 SQL 文件会自动执行。虽然没有一个独立的 supabase seed 命令来单独执行此操作，但数据填充是本地开发工作流的一个集成部分。

supabase inspect report - 审查数据库统计信息

此命令用于检查数据库的各项统计数据，并可以将报告保存为 CSV 文件。这对于性能分析、监控数据库健康状况和了解数据库对象的使用情况非常有用。

语法

supabase inspect report [flags]

选项 (Flags)

选项	描述
--output-dir <string>	（可选）指定保存 CSV 文件的目录路径。
--linked	（可选）审查已关联的远程项目。
--local	（可选）审查本地数据库。

---

第三章：项目、组织与配置

除了管理单个项目的代码和数据库模式，Supabase CLI 还提供了管理 Supabase 平台上的高级资源的强大功能。这些资源包括组织（Organizations）和项目（Projects）本身，以及它们的配置。本章将详细介绍如何通过命令行来创建、列出和管理这些实体，使您能够以脚本化的方式进行环境搭建和团队协作。

3.1 组织管理 (orgs)

在 Supabase 中，组织是项目的容器，用于团队协作和计费管理。supabase orgs 命令组允许您直接从终端管理您的组织。

supabase orgs list - 列出所有组织

此命令用于列出当前登录用户所属的所有组织。

语法

supabase orgs list

执行后，将返回一个包含组织 ID 和名称的列表。

supabase orgs create - 创建新组织

此命令用于为当前登录用户创建一个新的组织。

语法

supabase orgs create <organization-name>

参数

• <organization-name>: 新组织的名称。

3.2 项目管理 (projects)

项目是 Supabase 的核心单元，包含了数据库、API、身份验证等所有服务。supabase projects 命令组使项目的创建和管理自动化成为可能，这对于 CI/CD 和可重复的环境部署至关重要。

supabase projects list - 列出所有项目

此命令列出当前登录用户有权访问的所有 Supabase 项目。

语法

supabase projects list

输出将包含每个项目的 ID、名称、组织和区域等信息。

supabase projects create - 创建新项目

此命令允许您以编程方式在指定的组织中创建一个新的 Supabase 项目。

语法

supabase projects create <project-name> [flags]

参数

• <project-name>: 新项目的名称。

选项 (Flags)

选项	描述
--db-password <string>	（必选）设置新项目数据库的密码。
--org-id <string>	（必选）指定要在哪个组织下创建项目。
--region <string>	（必选）选择项目部署的区域，例如 ap-southeast-1。
--size <string>	（可选）选择项目的实例大小。

supabase projects api-keys - 显示项目 API 密钥

此命令用于检索指定项目的 API 密钥，包括 anon_key 和 service_role_key。

语法

supabase projects api-keys [flags]

选项 (Flags)

选项	描述
--project-ref <string>	（必选）指定要查询密钥的项目引用 ID。

supabase projects delete - 删除项目

此命令用于永久删除一个 Supabase 项目。这是一个危险操作，请谨慎使用。

语法

supabase projects delete <project-ref>

参数

• <project-ref>: 要删除的项目的引用 ID。

3.3 项目配置 (config)

supabase config push - 推送项目配置

此命令用于将本地文件中的配置推送到您的 Supabase 项目。这对于管理和同步不同环境间的复杂配置（例如身份验证提供商设置）非常有用 32。

语法

supabase config push [flags]

选项 (Flags)

选项	描述
--config-path <string>	（必选）要推送的配置文件的路径。
--project-ref <string>	（可选）指定 Supabase 项目的引用 ID。如果未提供，则使用已关联的项目

---

第四章：云功能与环境管理

现代应用开发越来越依赖于无服务器计算和高效的环境隔离。Supabase CLI 在这两个方面提供了强大的支持。本章将深入探讨如何使用 CLI 管理边缘函数（Edge Functions）的整个生命周期，以及如何利用预览分支（Preview Branches）为每个功能或修复创建独立的、全功能的开发环境。

4.1 边缘函数 (functions)

边缘函数是部署在全球边缘网络上的 Deno TypeScript 函数，能够以极低的延迟响应用户请求。supabase functions 命令组为您提供了在本地开发、测试、部署和管理这些函数所需的一切工具。

supabase functions new - 创建新函数

此命令用于在 supabase/functions 目录下创建一个新的边缘函数，并生成包含样板代码的 index.ts 文件 。

语法

supabase functions new <function-name>

参数

• <function-name>: 新函数的名称，也将是其目录的名称 。

supabase functions list - 列出所有函数

此命令列出已部署到已关联的 Supabase 项目中的所有边缘函数。

语法

supabase functions list [flags]

supabase functions download - 下载函数

此命令用于从已关联的 Supabase 项目下载指定函数的源代码到本地。

语法

supabase functions download <function-name> [flags]

supabase functions serve - 本地运行函数

此命令在本地启动一个服务来运行和测试您所有的边缘函数，模拟了真实的云端环境。它还支持强大的调试功能 37。

语法

supabase functions serve [flags]

选项 (Flags)

选项	描述
--env-file <string>	指定一个 .env 文件，其内容将作为环境变量注入到函数中。
--no-verify-jwt	禁用对传入请求的 JWT 令牌的验证，方便本地测试。
--inspect / --inspect-mode	激活 Deno 的 v8 检查器协议，允许使用 Chrome DevTools 或 VS Code 等工具进行断点调试 。

supabase functions deploy - 部署函数

此命令将本地的一个或所有边缘函数部署到已关联的 Supabase 项目。

语法

supabase functions deploy [function-name][flags]

参数

• [function-name]: （可选）如果提供，则只部署指定的函数。否则，将部署所有函数。

选项 (Flags)

选项	描述
--no-verify-jwt	部署的函数将禁用 JWT 验证。
--project-ref <string>	指定要部署到的项目引用 ID。
--prune	删除那些存在于远程项目但不存在于本地的函数。

supabase functions delete - 删除函数

此命令从已关联的 Supabase 项目中删除指定的边缘函数。注意，此操作不会删除本地的函数文件 39。

语法

Bash

supabase functions delete <function-name> [flags]

4.2 环境变量 (secrets)

为了安全地管理边缘函数中使用的敏感信息（如 API 密钥、密码等），您应该使用环境变量。supabase secrets 命令组允许您安全地管理这些值。

supabase secrets list - 列出所有环境变量

此命令列出已为关联项目设置的所有环境变量的名称。

语法

supabase secrets list

supabase secrets set - 设置环境变量

此命令用于为一个或多个环境变量设置值。您可以直接在命令行中提供键值对，或从一个 .env 文件中批量设置。

语法

supabase secrets set NAME1=VALUE1 NAME2=VALUE2...

或者

supabase secrets set --env-file /path/to/your.env

supabase secrets unset - 取消设置环境变量

此命令用于从项目中删除一个或多个环境变量。

语法

supabase secrets unset NAME1 NAME2...

4.3 预览分支 (branches)

预览分支是 Supabase 提供的一项强大功能，它允许您为代码仓库中的每个 Git 分支创建一个独立的、临时的 Supabase 项目副本。每个预览分支都有自己的数据库和边缘函数部署，非常适合在合并到主分支之前进行功能测试、代码审查和端到端验证。

supabase branches create - 创建预览分支

此命令为已关联的项目创建一个新的预览分支。

语法

supabase branches create [name][flags]

选项 (Flags)

选项	描述
--git-branch <string>	关联到指定的 Git 分支名称 。
--region <string>	为分支数据库选择一个部署区域。

supabase branches list - 列出所有预览分支

此命令列出已关联项目的所有预览分支 。

语法

supabase branches list

supabase branches get - 获取分支详情

此命令检索指定预览分支的详细信息，包括其数据库连接字符串和 API URL。

语法

supabase branches get <name>

supabase branches update - 更新预览分支

此命令用于更新一个现有预览分支的属性，例如重命名或更改其关联的 Git 分支。

语法

supabase branches update <name> [flags]

supabase branches pause - 暂停预览分支

此命令用于暂停一个不活跃的预览分支以节省资源。

语法

supabase branches pause <name>

supabase branches unpause - 取消暂停预览分支

此命令用于重新激活一个已暂停的预览分支。

语法

supabase branches unpause <name>

supabase branches delete - 删除预览分支

此命令永久删除一个预览分支及其所有相关资源（包括数据库）。

语法

supabase branches delete <name>

---

第五章：高级平台管理

本章涵盖了对 Supabase 平台进行高级配置和管理的命令。这些功能通常涉及项目的网络安全、域名路由、身份验证集成和数据库性能调优，对生产环境的稳定性和安全性至关重要。

重要提示：实验性功能

本章中的许多命令，特别是与自定义域名、网络限制和 SSL 强制相关的命令，可能需要添加 --experimental 标志才能执行。这个标志表明该功能可能仍在积极开发中，其 API 或行为在未来版本中可能会发生变化。在使用这些高级功能时，强烈建议您首先在非生产环境中进行充分测试，并查阅最新的 Supabase 官方公告以了解其稳定性和最佳实践。请谨慎操作，以避免对您的项目造成意外影响。

5.1 对象存储 (storage)

supabase storage 命令组提供了一套类似 Unix 文件系统命令的工具，用于与 Supabase Storage 进行交互，方便您通过脚本管理存储桶和对象。

supabase storage ls - 列出对象

此命令用于列出指定存储桶或路径下的所有对象和文件夹。

语法

supabase storage ls [path][flags]

选项 (Flags)

选项	描述
-r, --recursive	递归地列出所有子目录中的内容。

supabase storage cp - 复制对象

此命令用于在本地文件系统和 Supabase Storage 之间上传或下载文件，或者在 Storage 内部复制对象。

语法

supabase storage cp <source> <destination> [flags]

参数

• <source>: 源文件路径（本地路径或 sb://bucket/path 格式的远程路径）。
• <destination>: 目标文件路径（本地路径或 sb://bucket/path 格式的远程路径）。

选项 (Flags)

选项	描述
-r, --recursive	递归地复制整个目录 。

supabase storage mv - 移动或重命名对象

此命令用于在 Supabase Storage 内部移动或重命名对象 。

语法

supabase storage mv <source> <destination> [flags]

supabase storage rm - 删除对象

此命令用于从 Supabase Storage 中删除一个或多个对象 。

语法

supabase storage rm <path>... [flags]

选项 (Flags)

选项	描述
-r, --recursive	递归地删除整个目录及其内容。

5.2 单点登录 (sso)

supabase sso 命令组用于管理您项目的企业级单点登录（SSO）身份提供商，目前主要支持 SAML 2.0 协议 。

supabase sso add - 添加身份提供商

此命令用于为您的项目添加一个新的 SSO 身份提供商配置。

语法

supabase sso add [flags]

选项 (Flags)

选项	描述
--type <[ saml ]>	（必选）指定提供商的协议类型。
--metadata-file <string>	提供包含 SAML 2.0 元数据 XML 的文件路径。
--metadata-url <string>	提供指向 SAML 2.0 元数据 XML 的 URL。
--domains <strings>	关联到此提供商的电子邮件域名列表，以逗号分隔。

supabase sso list - 列出所有身份提供商

此命令列出项目上已配置的所有 SSO 身份提供商。

语法

supabase sso list

supabase sso show - 显示提供商信息

此命令显示指定 SSO 身份提供商的详细配置信息。

语法

supabase sso show <provider-id>

supabase sso info - 显示项目的 SSO 信息

此命令返回您的项目用于在身份提供商处注册所需的 SSO 信息，例如实体 ID 和断言消费者服务 (ACS) URL。

语法

supabase sso info

supabase sso update - 更新身份提供商

此命令用于更新一个已存在的 SSO 身份提供商的配置。

语法

supabase sso update <provider-id> [flags]

supabase sso remove - 移除身份提供商

此命令用于从项目中删除一个 SSO 身份提供商的配置。这是一个危险操作，会导致依赖此提供商的用户无法登录 62。

语法

Bash

supabase sso remove <provider-id>

5.3 自定义域名 (domains & vanity-subdomains)

Supabase 允许您为项目配置自定义域名，以提供更专业的品牌体验。您可以选择使用自定义主机名（Custom Hostnames）或虚荣子域名（Vanity Subdomains），但两者是互斥的 63。

supabase domains - 管理自定义主机名

这个命令组用于将您自己的域名（例如 api.yourcompany.com）指向您的 Supabase 项目 63。

• create: 创建一个新的自定义主机名配置 65。
• get: 检索当前的自定义主机名配置 66。
• reverify: 重新验证自定义主机名的 DNS 配置 67。
• activate: 激活自定义主机名，将项目流量切换到该域名 68。
• delete: 删除自定义主机名配置 69。

supabase vanity-subdomains - 管理虚荣子域名

这个命令组用于为您的项目设置一个更易记的 .supabase.co 子域名（例如 your-project.supabase.co） 64。

• check-availability: 检查所需的子域名是否可用 70。
• get: 检索项目当前的虚荣子域名配置 71。
• activate: 激活虚荣子域名 72。
• delete: 删除虚荣子域名，恢复为使用项目引用 ID 的默认域名 73。

5.4 网络管理 (network-bans & network-restrictions)

为了保护您的项目免受滥用和未经授权的访问，CLI 提供了网络层面的访问控制工具。

supabase network-bans - 管理网络封禁

如果某个 IP 地址的流量模式看起来具有滥用性（例如，多次失败的登录尝试），它可能会被自动临时封禁。这个命令组允许您查看和管理这些封禁 74。

• get: 检索当前被封禁的 IP 地址列表 75。
• remove: 移除对指定 IP 地址的封禁 76。

supabase network-restrictions - 管理网络限制

此功能允许您配置一个 IP 地址允许列表（CIDR 范围），只有来自这些 IP 地址的请求才能访问您的数据库。这是保护生产数据库的强大安全措施 77。

• get: 检索当前的网络限制配置 78。
• update: 更新网络限制，设置允许的 CIDR 地址列表 79。

5.5 SSL 与 Postgres 配置

supabase ssl-enforcement - 管理 SSL 强制

此命令组用于管理项目数据库的 SSL 连接强制策略 80。

• get: 检索当前的 SSL 强制配置 81。
• update: 启用或禁用数据库的 SSL 强制连接 82。

supabase postgres-config - 管理 Postgres 配置

此命令组允许您直接覆盖和管理项目数据库的 Postgres 配置参数 (postgresql.conf)，以进行性能调优 83。

• get: 检索当前已覆盖的 Postgres 配置 84。
• update: 更新或设置 Postgres 配置参数 85。
• delete: 删除 Postgres 配置覆盖，恢复为默认值 86。

---

第六章：实用工具与脚本

本章介绍 Supabase CLI 提供的一系列实用工具，它们旨在提升开发体验、增强代码质量和简化日常任务。这些工具包括从数据库模式自动生成类型定义、管理 SQL 代码片段、运行数据库测试，以及与您的 Shell 环境集成以实现命令自动补全。

6.1 类型生成 (gen)

supabase gen 命令组是连接后端数据库和前端应用程序的桥梁，它能够自动生成代码，从而提高开发效率和代码的类型安全性。

supabase gen types - 从数据库模式生成类型

此命令是 Supabase CLI 最有价值的功能之一。它会连接到您的数据库（本地或远程），检查其模式（包括表、视图、函数和自定义类型），并自动生成相应的 TypeScript、Go 或 Swift 类型定义。

用途

生成的类型定义可以让您在编写前端代码时获得完整的类型提示和自动补全，从而在编译时就能捕捉到对数据库的错误调用，极大地减少了运行时错误，提升了开发体验。

语法

supabase gen types [flags]

选项 (Flags)

| 选项 | 描述 |
|--------------------------|----------------------|--------------|----------------------------------|
| `--lang <[ typescript | go | swift ]>` | 指定生成的类型定义所用的语言，默认为 typescript。 |
| --local | 从本地开发数据库生成类型。 |
| --linked | 从已关联的远程项目生成类型。 |
| -s, --schema <strings> | 指定要包含的数据库模式列表，以逗号分隔。 |

示例

从本地数据库为 public 模式生成 TypeScript 类型，并输出到标准输出：

supabase gen types --local --schema public

通常，您会将其重定向到一个文件中，例如 types/supabase.ts。

supabase gen signing-key - 生成 JWT 签名密钥

此命令用于安全地生成一个用于 JWT 签名的私钥。这在您需要自定义 JWT 或在本地验证令牌时非常有用。

语法

supabase gen signing-key [flags]

选项 (Flags)

选项	描述
--algorithm <>	指定签名算法，推荐使用 ES256。
--append	将新密钥附加到现有密钥文件中，而不是覆盖。

6.2 SQL 代码片段 (snippets)

supabase snippets 命令组允许您管理保存在 Supabase 仪表盘 SQL 编辑器中的代码片段。

supabase snippets list - 列出所有代码片段

此命令列出您项目中的所有 SQL 代码片段。

语法

supabase snippets list

supabase snippets download - 下载代码片段内容

此命令根据代码片段的 ID 下载其 SQL 内容。

语法

supabase snippets download <snippet-id>

6.3 测试 (test)

Supabase CLI 集成了对 pgTAP 的支持，这是一个用于 PostgreSQL 的测试框架。您可以用它来为您的数据库函数、触发器、RLS 策略等编写单元测试。

supabase test new - 创建新测试

此命令在 supabase/tests 目录下创建一个新的测试文件模板。

语法

supabase test new <test-name>

supabase test db - 运行数据库测试

此命令在本地数据库上执行 supabase/tests 目录下的所有 pgTAP 测试。它会在一个隔离的容器中运行 pg_prove，并报告测试结果。

语法

supabase test db [path]... [flags]

参数

• [path]...: （可选）指定要运行的特定测试文件或目录的路径 95。

6.4 服务信息 (services)

supabase services - 显示所有服务版本

此命令用于显示本地开发环境中运行的所有 Supabase 服务的版本信息。这对于调试和报告问题非常有用。

语法

supabase services

6.5 Shell 自动补全 (completion)

为了提高使用 CLI 的效率，supabase completion 命令可以为多种流行的 Shell 生成自动补全脚本。启用后，您可以通过按 Tab 键来自动补全命令和选项。

supabase completion bash - 为 Bash 生成脚本

生成 Bash shell 的自动补全脚本。您需要确保已安装 bash-completion 包。

加载说明 (Linux)

要为所有新会话加载补全，执行一次：

supabase completion bash > /etc/bash_completion.d/supabase

supabase completion zsh - 为 Zsh 生成脚本

生成 Zsh shell 的自动补全脚本。

加载说明 (macOS, via Homebrew)

要为所有新会话加载补全，执行一次：

supabase completion zsh > $(brew --prefix)/share/zsh/site-functions/_supabase

supabase completion fish - 为 Fish 生成脚本

生成 Fish shell 的自动补全脚本。

加载说明

要为所有新会话加载补全，执行一次：

supabase completion fish > ~/.config/fish/completions/supabase.fish

supabase completion powershell - 为 PowerShell 生成脚本

生成 PowerShell 的自动补全脚本。

加载说明

要为当前会话加载补全，执行：

supabase completion powershell | Out-String | Invoke-Expression

要为所有新会话加载，请将此命令添加到您的 PowerShell 配置文件中。

---

附录：命令速查表

此速查表旨在为熟悉 Supabase CLI 的用户提供一个快速参考。它按功能模块对所有主要命令及其子命令进行了分层组织。

命令	描述
通用 (General)
supabase init	初始化本地项目配置。
supabase login	登录到您的 Supabase 账户。
supabase link	将本地项目关联到一个远程 Supabase 项目。
supabase start	启动本地开发所需的所有 Docker 容器。
supabase stop	停止所有本地运行的容器。
supabase status	检索本地容器的状态和连接信息。
数据库 (Database)
supabase db start	仅启动本地数据库容器。
supabase db pull	从远程数据库拉取模式变更。
supabase db push	将本地迁移推送到远程数据库。
supabase db reset	重置本地数据库并应用所有迁移。
supabase db dump	从远程数据库转储模式。
supabase db diff	比对本地数据库的模式差异。
supabase db lint	检查本地数据库模式中的错误。
迁移 (Migrations)
supabase migration new	创建一个新的数据库迁移文件。
supabase migration list	列出所有本地和远程的迁移及其状态。
supabase migration up	应用所有待定的迁移文件。
supabase migration repair	修复迁移历史表中的不一致。
supabase migration squash	将多个迁移合并为一个文件。
supabase migration fetch	从历史表中获取迁移文件。
边缘函数 (Edge Functions)
supabase functions new	创建一个新的边缘函数。
supabase functions list	列出所有已部署的函数。
supabase functions download	下载一个已部署的函数。
supabase functions serve	在本地运行和测试函数。
supabase functions deploy	部署一个或所有函数。
supabase functions delete	删除一个已部署的函数。
项目管理 (Projects)
supabase projects create	创建一个新的 Supabase 项目。
supabase projects list	列出您所有的项目。
supabase projects api-keys	显示一个项目的 API 密钥。
supabase projects delete	删除一个项目。
组织管理 (Organizations)
supabase orgs create	创建一个新的组织。
supabase orgs list	列出您所有的组织。
环境变量 (Secrets)
supabase secrets set	为项目设置一个或多个环境变量。
supabase secrets list	列出项目的所有环境变量。
supabase secrets unset	从项目中移除一个或多个环境变量。
测试 (Testing)
supabase test db	针对本地数据库运行 pgTAP 测试。
supabase test new	创建一个新的测试文件。
类型生成 (Generate Types)
supabase gen types	从数据库模式生成类型定义。
supabase gen signing-key	生成一个 JWT 签名密钥。
存储 (Storage)
supabase storage ls	列出存储对象。
supabase storage cp	上传或下载存储对象。
supabase storage mv	移动或重命名存储对象。
supabase storage rm	删除存储对象。
Shell 自动补全 (Autocompletion)
supabase completion bash	为 Bash 生成自动补全脚本。
supabase completion zsh	为 Zsh 生成自动补全脚本。
supabase completion fish	为 Fish 生成自动补全脚本。
supabase completion powershell	为 PowerShell 生成自动补全脚本。