Supabase 命令行工具

Develop locally, deploy to the Supabase Platform, and set up CI/CD workflows

Supabase CLI 可以在你自己的电脑或 CI 环境中运行整个 Supabase 堆栈，这样你就可以本地构建和测试，然后在准备好部署时将你的项目连接到托管版本。

🌐 The Supabase CLI runs the entire Supabase stack on your own machine or in a CI environment, so you can build and test locally, then connect your project to a hosted one when you're ready to deploy.

Quickstart 是两条命令的版本，如果你已经有了 CLI 和容器运行时。
设置本地项目会安装 CLI 并在你的电脑上启动整个环境。如果你以前没运行过，从这里开始。
连接到托管项目会将你的本地目录链接到 Supabase 平台上的一个项目。
更改你的 CLI 版本会更新 CLI，并在稳定版和预览版之间切换。
遥测涵盖了 CLI 收集的信息以及如何选择退出。

快速入门 #

🌐 Quickstart

只需两个命令，你就可以创建并启动一个新的本地项目：

🌐 With two commands, you can set up and start a new local project:

运行 supabase init 来创建一个新的本地项目。
运行 supabase start 来启动 Supabase 服务。

全局命令或项目依赖

你如何运行一个 CLI 命令取决于你是如何安装它的。Homebrew、Scoop 和 Linux 软件包会给你一个全局的 supabase 命令。用 npm、pnpm、yarn 或 bun 安装则会把 CLI 添加到某个项目里，这样你就要通过你的包管理器以 npx supabase <command> 运行它。本页的所有示例都写成 supabase <command>。

🌐 How you run a CLI command depends on how you install it. Homebrew, Scoop, and the Linux packages give you a global supabase command. Installing with npm, pnpm, yarn, or bun adds the CLI to one project instead, so you run it through your package runner as npx supabase <command>. This page writes every example as supabase <command>.

无论哪种方式，CLI 都是以项目为范围的。大多数命令，包括 start，都需要一个目录，而这个目录已经被 supabase init 设置好了，其中包含一个 supabase 目录和一个 config.toml。先运行 init，然后在同一目录下运行其他命令。

🌐 The CLI is project-scoped either way. Most commands, including start, expect a directory that supabase init has already set up with a supabase directory and a config.toml. Run init first, then the rest from the same directory.

建立本地项目 #

🌐 Set up a local project

安装 CLI，在你的电脑上启动 Supabase 堆栈，完成后再停止它。

🌐 Install the CLI, bring the Supabase stack up on your machine, and stop it when you're done.

安装 Supabase CLI #

🌐 Install the Supabase CLI [#installing-the-supabase-cli]

将 CLI 安装为项目的开发依赖。这条命令会把 CLI 添加到单个项目中，而不是安装一个全局命令：
```
1
npm install supabase --save-dev
2
# or: pnpm add -D supabase / yarn add -D supabase / bun add -D supabase
```
在 package.json 中固定版本，这样你们整个团队就能使用相同的 CLI 版本。

通过你的包管理器运行 CLI:

1
npx supabase --help
2
# or: pnpm supabase / yarn supabase / bunx supabase

通过 npx 或 npm 运行时，Supabase CLI 需要 Node.js 20 或更高版本。旧版本的 Node.js，比如 16，是不支持的，会启动失败。

🌐 The Supabase CLI requires Node.js 20 or later when run via npx or npm. Older Node.js versions, such as 16, are not supported and fail to start the CLI.

运行本地 Supabase 项目 #

🌐 Run a local Supabase project [#running-a-local-supabase-project]

使用 CLI 最常做的事情就是在你自己的机器上运行完整的 Supabase 堆栈（Postgres、Auth、Storage 和其他服务）。这个堆栈运行在 Docker 容器中，所以你首先需要安装一个容器运行环境。在 Windows 和 Linux 上，可以按照官方指南安装和配置 Docker Desktop。

🌐 The most common thing you'll do with the CLI is run the full Supabase stack (Postgres, Auth, Storage, and the rest) on your own machine. That stack runs in Docker containers, so you need a container runtime installed first. On Windows and Linux, follow the official guide to install and configure Docker Desktop.

在 macOS 上，我们推荐使用 OrbStack 替代 Docker Desktop。它是一个即插即用的替代方案，比 Docker Desktop 在挂载卷的扩展文件属性（xattrs）和容器网络方面更可靠。同时，它启动更快，占用的 CPU、内存和磁盘更少，在运行完整的 Supabase 堆栈时差别非常明显。

🌐 On macOS, we recommend OrbStack instead of Docker Desktop. It's a drop-in replacement that handles extended file attributes (xattrs) on mounted volumes and container networking more reliably than Docker Desktop. It also starts faster and uses less CPU, memory, and disk, which makes a noticeable difference when running the full Supabase stack.

或者，你也可以使用提供 Docker 兼容 API 的其他容器工具：

🌐 Alternatively, you can use a different container tool that offers Docker-compatible APIs:

工具	平台
Rancher Desktop	macOS, Windows, Linux
Podman	macOS, Windows, Linux
colima	macOS

把堆栈调高：

🌐 To bring the stack up:

启动你的容器运行时。
在你想创建项目的目录里打开一个终端。
初始化项目：
```
1
supabase init
```
该命令会创建一个 supabase 目录，安全地提交到版本控制中。init 只会创建本地文件：不会帮你登录，也不会将目录连接到 Supabase 平台上的项目。要连接项目，请参见连接到托管项目。
从同一个目录启动 Supabase 服务：
```
1
supabase start
```

如果你用 npm、pnpm、yarn 或 bun 将 CLI 安装为项目依赖，请改为运行 npx supabase init 和 npx supabase start。参见安装 Supabase CLI。

🌐 If you installed the CLI as a project dependency with npm, pnpm, yarn, or bun, run npx supabase init and npx supabase start instead. See Install the Supabase CLI.

第一次运行时会花一些时间，因为 CLI 需要下载 Docker 镜像。它会拉取整个 Supabase 堆栈，以及一些对本地开发有用的额外镜像，比如本地 SMTP 服务器和数据库差异工具。

🌐 The first run takes time while the CLI downloads the Docker images. It pulls the entire Supabase stack, plus a few extra images useful for local development, such as a local SMTP server and a database diff tool.

访问你项目的服务 #

🌐 Access your project's services

在所有 Supabase 服务运行后，CLI 会打印出你的本地凭证。输出看起来像这样，里面包含你在本地项目中使用的 URL 和密钥：

🌐 After all the Supabase services are running, the CLI prints your local credentials. The output looks like this, with the URLs and keys you use in your local project:

1
Started supabase local development setup.
2
3
╭──────────────────────────────────────╮
4
│ 🔧 Development Tools                 │
5
├─────────┬────────────────────────────┤
6
│ Studio  │ http://127.0.0.1:54323     │
7
│ Mailpit │ http://127.0.0.1:54324     │
8
│ MCP     │ http://127.0.0.1:54321/mcp │
9
╰─────────┴────────────────────────────╯
10
11
╭──────────────────────────────────────────────────────╮
12
│ 🌐 APIs                                              │
13
├────────────────┬─────────────────────────────────────┤
14
│ Project URL    │ http://127.0.0.1:54321              │
15
│ REST           │ http://127.0.0.1:54321/rest/v1      │
16
│ GraphQL        │ http://127.0.0.1:54321/graphql/v1   │
17
│ Edge Functions │ http://127.0.0.1:54321/functions/v1 │
18
╰────────────────┴─────────────────────────────────────╯
19
20
╭───────────────────────────────────────────────────────────────╮
21
│ ⛁ Database                                                    │
22
├─────┬─────────────────────────────────────────────────────────┤
23
│ URL │ postgresql://postgres:postgres@127.0.0.1:54322/postgres │
24
╰─────┴─────────────────────────────────────────────────────────╯
25
26
╭──────────────────────────────────────────────────────────────╮
27
│ 🔑 Authentication Keys                                       │
28
├─────────────┬────────────────────────────────────────────────┤
29
│ Publishable │ sb_publishable_...                             │
30
│ Secret      │ sb_secret_...                                  │
31
╰─────────────┴────────────────────────────────────────────────╯

1
# Default URL:
2
http://localhost:54323

本地开发环境包括 Supabase Studio，这是一个用于查询和编辑数据库的图形界面。

🌐 The local development environment includes Supabase Studio, a graphical interface for querying and editing your database.

Local Supabase Studio showing the Default Project home page, with a sidebar of section icons, a Client libraries row for JavaScript, Python, and Flutter, and a grid of example project cards.

停止本地服务 #

🌐 Stop local services [#stopping-local-services]

当你工作结束时，停止堆栈。停止不会重置你的本地数据库：

🌐 When you finish working, stop the stack. Stopping doesn't reset your local database:

1
supabase stop

使用默认端口时，supabase start 每台机器只能运行一个本地项目，因为每个项目的 config.toml 都使用相同的端口。要同时运行多个本地项目或 git 工作树，请参见运行多个本地项目。

🌐 With the default ports, supabase start runs one local project per machine, because every project's config.toml uses the same ports. To run several local projects or git worktrees at the same time, see Running multiple local projects.

连接到托管项目 #

🌐 Connect to a hosted project

你在 Run a local Supabase project 中启动的堆栈只会在你的电脑上运行。在你登录 CLI 并将本地目录链接到某个项目之前，什么都不会到达托管项目。

🌐 The stack you started in Run a local Supabase project runs only on your machine. Nothing reaches a hosted project until you sign in to the CLI and link your local directory to one.

有关步骤，请参见推送到远程项目。要从 CI 运行部署，请参见配置 GitHub Actions。

🌐 For the steps, see Pushing to a remote project. To run deployments from CI, see Configure GitHub Actions.

更改你的 CLI 版本 #

🌐 Change your CLI version

这些部分讲的是命令行本身，而不是你本地的项目。

🌐 These sections cover the CLI itself rather than your local project.

使用测试版通道 #

🌐 Use the beta channel [#beta-channel]

预发布的 CLI 构建版本来自开发分支，版本标识为 X.Y.Z-beta.N。使用 npm beta dist-tag，或者通过 Homebrew 或 Scoop 安装 supabase-beta。supabase-beta 是一个独立于 supabase 的包。

🌐 Pre-release CLI builds ship from the development branch and are versioned X.Y.Z-beta.N. Use the npm beta dist-tag, or install supabase-beta with Homebrew or Scoop. supabase-beta is a separate package from supabase.

作为开发依赖安装：

🌐 Install as a dev dependency:

1
npm install supabase@beta --save-dev

或者直接运行，无需安装：

🌐 Or run without installing:

1
npx supabase@beta --help

更新 Supabase CLI #

🌐 Update the Supabase CLI [#updating-the-supabase-cli]

用你安装它时用的同一个包管理器更新 CLI。可在 CLI 发布页面查看可用版本。

🌐 Update the CLI with the same package manager you installed it with. See the CLI releases page for available versions.

使用 npm 更新 CLI：

🌐 Update the CLI with npm:

1
npm update supabase --save-dev

更新到当前测试版，或将稳定版切换到测试版渠道：

🌐 Update to the current beta release, or switch a stable install to the beta channel:

1
npm install supabase@beta --save-dev

如果你本地有在运行的 Supabase 容器，升级前先停止它们并删除它们的数据卷。删除数据卷可以让 Supabase 托管服务在干净的本地数据库上应用新的迁移。

🌐 If you have any Supabase containers running locally, stop them and delete their data volumes before upgrading. Deleting the volumes lets Supabase managed services apply new migrations on a clean local database.

停车前倒车

supabase stop --no-backup 会删除你本地的 schema 和数据更改。先保存它们哦。

把本地模式更改保存为迁移：
```
1
supabase db diff -f my_schema
```

把本地数据导出到你的种子文件：

1
supabase db dump --local --data-only > supabase/seed.sql

停止容器并删除它们的数据卷：
```
1
supabase stop --no-backup
```

遥测 #

🌐 Telemetry

Supabase CLI 会收集有关一般使用情况的遥测数据。参与这个计划是可选的，你可以随时选择退出。

🌐 The Supabase CLI collects telemetry data about general usage. Participating in this program is optional, and you can opt out at any time.

如何退出 #

🌐 How to opt out

禁用遥测：
```
1
supabase telemetry disable
```
确认当前设置：
```
1
supabase telemetry status
```

要再次启用遥测，请运行 supabase telemetry enable。

🌐 To enable telemetry again, run supabase telemetry enable.

你也可以通过使用 SUPABASE_TELEMETRY_DISABLED=1 环境变量选择退出。更广泛的 DO_NOT_TRACK=1 约定同样会被遵守。

🌐 You can also opt out using the SUPABASE_TELEMETRY_DISABLED=1 environment variable. The broader DO_NOT_TRACK=1 convention is also respected.

了解更多 #

🌐 Learn more