Docker 和本地运行时

本指南解释了实验性 supabase stack 命令使用的两种运行时、CLI 如何选择其中一个，以及该选择哪一个。Docker 运行时会在容器中运行每个服务，使用 Docker 或 Podman。原生运行时则会在你的机器上以进程的形式运行每个服务，不使用容器引擎，适用于 Linux 和 Apple 芯片的 macOS。

🌐 This guide explains the two runtimes the experimental supabase stack commands use, how the CLI picks one, and which to choose. The Docker runtime runs each service in a container, with Docker or Podman. The native runtime runs each service as a process on your machine, with no container engine, on Linux and on macOS on Apple silicon.

两个运行时都运行相同的本地 Supabase 项目及其相同的服务。默认的 supabase start 命令总是使用 Docker。只有在你开启 [experimental] stack 设置后，才可以选择运行时。查看 运行多个本地项目 了解如何开启。

🌐 Both runtimes run the same local Supabase project with the same services. The default supabase start command always uses Docker. The runtime choice exists only after you turn on the [experimental] stack setting. See Running multiple local projects for how to turn it on.

选择哪个运行时 #

🌐 Which runtime to choose

当 Docker 或 Podman 可用时，请使用 Docker。容器给每个本地项目自己的网络命名空间和文件系统。这种隔离在你在一台机器上运行多个本地项目时最为重要。

🌐 Use Docker when Docker or Podman is available. Containers give each local project its own network namespace and file system. That isolation matters most when you run several local projects on one machine.

在没有容器引擎的情况下使用本地运行时，比如编码代理沙箱和 CI 运行器。本地运行时适用于每个环境一个本地项目。本地进程会共享主机的进程表和文件锁。同一台机器上的多个本地项目之间的隔离性比容器要差。

🌐 Use the native runtime where no container engine is available, such as coding agent sandboxes and CI runners. The native runtime is intended for one local project per environment. Native processes share the host's process table and file locks. Several native local projects on one machine are less isolated from each other than containers are.

这两个运行时有何不同 #

🌐 How the two runtimes differ

下表对比了每种运行时如何运行服务、需要什么以及数据存储在哪里。

🌐 The following table compares how each runtime runs services, what it needs, and where it stores data.

Docker 本地项目会保留创建时的数据库存储。在 Docker 25 上创建的本地项目，在升级到 Docker 26 后会保留其主机目录。

🌐 A Docker local project keeps the database storage it was created with. A local project created on Docker 25 keeps its host directory after you upgrade to Docker 26.

两个运行时都会把每个本地项目的保存设置保存在 ~/.supabase/stacks/<id>/ 下。原生运行时也会把它的数据库数据保存在那里。如果你设置了 SUPABASE_HOME，CLI 就会使用那个目录，而不是 ~/.supabase。

在这两种运行时中，Postgres 会立即启动，而其他服务会在第一次请求时启动。默认情况下，这种方式启动的服务在空闲 60 秒后会停止，Studio 在 5 分钟后停止。函数不会自动停止。当有正在运行的服务依赖某个服务时，该服务也会保持运行，比如 Studio 运行时的 pgmeta。传入 --eager 可以在命令返回前启动所有已启用的服务，并关闭空闲停止功能。

🌐 In both runtimes, Postgres starts right away and other services start on their first request. By default, services that started this way stop again after 60 seconds idle, and Studio after 5 minutes. Functions doesn't stop on its own. A service also stays up while a running service depends on it, such as pgmeta while Studio runs. Pass --eager to start every enabled service before the command returns and turn off idle stops.

按需启动服务并不意味着按需下载它。默认情况下，第一次 supabase start 会在返回之前拉取或下载所有启用的服务。传入 --preparation on-demand 可以将每个下载延迟到服务的第一次请求时才进行。

🌐 Starting a service on demand doesn't mean downloading it on demand. By default, the first supabase start pulls or downloads every enabled service before it returns. Pass --preparation on-demand to defer each download until the service's first request.

CLI 是如何选择运行时的 #

🌐 How the CLI picks a runtime

当你没有传入 --runtime 时，一个新的本地项目会使用第一个回应的选项：

🌐 When you don't pass --runtime, a new local project uses the first of these that responds:

1. 当 Docker 守护进程返回 docker version 时，Docker
2. 当 Podman 引擎回答 podman info 时，Podman
3. 本地，在 Linux 上的 amd64 和 arm64，以及在 Apple Silicon 的 macOS 上

每个检查最多等待 10 秒。仅安装了 docker 命令是不够的。如果 Docker 守护进程停止了，CLI 会转而使用 Podman 或本地引擎。它会打印一条通知，说明跳过了 Docker，并提供切换步骤。在没有本地支持的平台上，如果没有响应的引擎，启动就会失败，并提示你启动 Docker 或 Podman。

🌐 Each check waits up to 10 seconds. Having the docker command installed isn't enough. If the Docker daemon is stopped, the CLI moves on to Podman or native. It prints a notice that it skipped Docker, with the steps to switch. With no responding engine on a platform without native support, the start fails and asks you to start Docker or Podman.

通过 --runtime docker、--runtime podman 或 --runtime native 需要那个运行时，并且 CLI 永远不会切换到其他运行时。如果 --runtime docker 无法访问 Docker，启动就会失败，并建议启动 Docker，或者在受支持的平台上用 --runtime native 创建一个新的本地项目。如果在不受支持的平台上使用 --runtime native，启动会在 CLI 创建本地项目之前就失败。

🌐 Passing --runtime docker, --runtime podman, or --runtime native requires that runtime, and the CLI never falls back to another one. If Docker isn't reachable with --runtime docker, the start fails and suggests starting Docker, or --runtime native for a new local project on a supported platform. With --runtime native on an unsupported platform, the start fails before the CLI creates the local project.

CLI 在创建本地项目时会记录运行时，并在之后的每次启动中重用它，而不会再次检查。给已经创建的本地项目传递不同的 --runtime 会失败。要将应用迁移到另一个运行时，可以创建一个新的命名本地项目，或者销毁本地项目后重新启动。CLI 不会在运行时之间转换数据。

🌐 The CLI records the runtime when it creates a local project and reuses it on every later start, without checking again. Passing a different --runtime to a local project that you already created fails. To move an app to another runtime, start a new named local project, or destroy the local project and start it again. The CLI doesn't convert data between runtimes.

同一台机器上的不同应用可以使用不同的运行时。

🌐 Different apps on one machine can use different runtimes.

本地运行时要求 #

🌐 Native runtime requirements

本地运行时在这些平台上运行：

🌐 The native runtime runs on these platforms:

本地运行时不能以 root 身份运行，因为 Postgres initdb 不能。要以 root 身份运行，比如在 CI 容器中，请将 SUPABASE_NATIVE_POSTGRES_USER 设置为非 root 账户。如果该账户不存在，先创建它。然后 CLI 会以该用户身份运行 Postgres。在一些支持的代码代理沙箱中，CLI 可以在没有设置这个变量的情况下找到合适的非 root 账户。

🌐 The native runtime doesn't run as root, because Postgres initdb can't. To run it as root, such as in a CI container, set SUPABASE_NATIVE_POSTGRES_USER to a non-root account. Create the account first if it doesn't exist. The CLI then runs Postgres as that user. In some supported coding agent sandboxes, the CLI finds a suitable non-root account without the variable.

首次启动时，CLI 会从 supabase/slim-services GitHub releases 下载服务归档，如果失败则使用 supabase-cli-artifacts.s3.us-east-1.amazonaws.com 作为备选。它会验证它们的校验和，并使用系统的 tar 解压，因此在最小化的沙箱镜像中需要安装 tar。在有允许列表的沙箱中，需要允许 S3 主机。如果想使用 GitHub 下载，则需要允许 github.com 和 release-assets.githubusercontent.com，因为 GitHub 会将版本下载重定向到那个主机。只允许 ghcr.io 是不够的。

🌐 On first start, the CLI downloads service archives from the supabase/slim-services GitHub releases, with supabase-cli-artifacts.s3.us-east-1.amazonaws.com as a fallback. It verifies their checksums and extracts them with the system tar, so install tar in minimal sandbox images. In a sandbox with an allowlist, allow the S3 host. To use GitHub instead, allow both github.com and release-assets.githubusercontent.com, because GitHub redirects release downloads to that host. Allowing only ghcr.io isn't enough.

如果想提前下载档案而不启动任何服务，比如在你构建沙盒镜像时，运行：

🌐 To download the archives ahead of time without starting any services, such as when you build a sandbox image, run:

1
supabase stack prepare --runtime native

如果本地项目不存在，prepare 会创建它，这样它就会出现在 supabase stack list 中，你可以使用 supabase stack destroy 将其移除。

🌐 If the local project doesn't exist, prepare creates it, so it appears in supabase stack list and you can remove it with supabase stack destroy.

~/.supabase/cache/stack 中的缓存被机器上的每个本地项目共享，而 supabase stack destroy 会将其保留在那里。删除该目录可以回收磁盘空间并强制重新下载。

🌐 The cache in ~/.supabase/cache/stack is shared by every local project on the machine, and supabase stack destroy leaves it in place. Delete that directory to reclaim its disk space and force a fresh download.

从一个特定的运行时开始 #

🌐 Start with a specific runtime

在本地运行环境中启动一个本地项目：

🌐 Start a local project in the native runtime:

1
supabase start --runtime native

为新本地项目需要 Docker：

🌐 Require Docker for a new local project:

1
supabase start --runtime docker

查看本地项目使用的是哪个运行时：

🌐 Check which runtime a local project uses:

1
supabase stack status --output-format json

runtime 字段是 docker、podman 或 native。supabase status 和 supabase stack list 的文本输出也显示了运行时间。

🌐 The runtime field is docker, podman, or native. The text output of supabase status and supabase stack list shows the runtime too.

限制 #

🌐 Limitations

• 本地项目会保留创建时使用的运行时，CLI 不会在运行时之间移动数据。请参阅 CLI 如何选择运行时。
• 在一台机器上运行几个本地原生项目是可行的，但它们共享主机资源，没有容器提供的隔离。如果是这种情况，可以使用 Docker。
• 如果 Postgres 在冷启动时准备就绪太慢，可以在 config.toml 的 [db] 下提高 health_timeout。两个运行时都使用这个设置。