配置

Configure your Supabase branches using configuration as code

本指南讲解了如何使用 config.toml 文件配置你的 Supabase 分支。在一个文件里，你可以配置所有分支，包括分支设置和密钥。

🌐 This guide covers how to configure your Supabase branches, using the config.toml file. In one single file, you can configure all your branches, including branch settings and secrets.

带远程的分支配置 #

🌐 Branch configuration with remotes

当启用分支时，你的 config.toml 设置会通过 Git 分支和 Supabase 分支的一对一对应，自动同步到所有临时分支。

🌐 When Branching is enabled, your config.toml settings automatically sync to all ephemeral branches through a one-to-one mapping between your Git and Supabase branches.

基本配置 #

🌐 Basic configuration

要更新 Supabase 分支的配置，修改 config.toml 然后推送到 git。Supabase 集成会检测到更改并将其应用到对应的分支。

🌐 To update configuration for a Supabase branch, modify config.toml and push to git. The Supabase integration will detect the changes and apply them to the corresponding branch.

远程专用配置 #

🌐 Remote-specific configuration

对于需要特定设置的持久分支，你可以在你的 config.toml 中使用 [remotes] 块。每个远程配置都必须引用一个已存在的项目 ID。

🌐 For persistent branches that need specific settings, you can use the [remotes] block in your config.toml. Each remote configuration must reference an existing project ID.

这是一个为预发布环境配置独立种子脚本的示例：

🌐 Here's an example of configuring a separate seed script for a staging environment:

1
[remotes.staging]
2
project_id = "your-project-ref"
3
[remotes.staging.db.seed]
4
enabled = true
5
sql_paths = ["./seeds/staging.sql"]

由于 project_id 字段必须引用已有的分支，因此在添加其配置之前，你需要先创建持久分支。先使用 CLI 创建一个持久分支吧：

🌐 Since the project_id field must reference an existing branch, you need to create the persistent branch before adding its configuration. Use the CLI to create a persistent branch first:

1
supabase --experimental branches create --persistent
2
# Do you want to create a branch named develop? [Y/n]

要获取现有分支的项目ID，请使用 branches list 命令：

🌐 To retrieve the project ID for an existing branch, use the branches list command:

1
supabase --experimental branches list

这将显示一个表格，展示你所有的分支以及它们对应的项目 ID。使用 BRANCH PROJECT ID 列的值作为远程配置中的 project_id。

🌐 This will display a table showing all your branches with their corresponding project ID. Use the value from the BRANCH PROJECT ID column as your project_id in the remote configuration.

配置合并 #

🌐 Configuration merging

当将 PR 合并到持久分支时，Supabase 集成会：

🌐 When merging a PR into a persistent branch, the Supabase integration:

检查配置更改
记录更改
把它们应用到目标远程

如果没有声明远程或项目 ID 错误，配置步骤会被跳过。

🌐 If no remote is declared or the project ID is incorrect, the configuration step is skipped.

可用的配置选项 #

🌐 Available configuration options

[remotes] 块中提供了所有标准配置选项，包括：

🌐 All standard configuration options are available in the [remotes] block. This includes:

数据库设置
API 配置
身份验证设置
边缘功能配置
还有更多

你可以用这个来为不同环境维护不同的配置，同时把它们都放进版本控制里。

🌐 You can use this to maintain different configurations for different environments while keeping them all in version control.

管理分支的密钥 #

🌐 Managing secrets for branches

对于像 SMTP 凭证或 API 密钥这样的敏感配置，你可以使用 Supabase CLI 来管理分支的密钥。这对于自定义 SMTP 设置或其他需要安全凭证的服务特别有用。

🌐 For sensitive configuration like SMTP credentials or API keys, you can use the Supabase CLI to manage secrets for your branches. This is especially useful for custom SMTP setup or other services that require secure credentials.

为持久分支设置秘密：

🌐 To set secrets for a persistent branch:

1
# Set secrets from a .env file
2
supabase secrets set --env-file ./supabase/.env
3
4
# Or set individual secrets
5
supabase secrets set SMTP_HOST=smtp.example.com
6
supabase secrets set SMTP_USER=your-username
7
supabase secrets set SMTP_PASSWORD=your-password

这些秘密将可以被你分支的服务使用，并且可以在你的配置中使用。例如，在你的 config.toml 中：

🌐 These secrets will be available to your branch's services and can be used in your configuration. For example, in your config.toml:

1
[auth.smtp]
2
host = "env(SMTP_HOST)"
3
user = "env(SMTP_USER)"
4
password = "env(SMTP_PASSWORD)"

秘密是分支专有的

为一个分支设置的秘密不会自动在其他分支中可用。你需要为每个需要它们的分支单独设置。

🌐 Secrets set for one branch are not automatically available in other branches. You'll need to set them separately for each branch that needs them.

在基于 Git 的工作流中使用 dotenvx #

🌐 Using dotenvx for git-based workflow

要在不同分支之间管理环境变量，你可以使用 dotenvx 来安全地管理你的配置。这种方法对使用 Git 分支和预览部署的团队特别有用。

🌐 For managing environment variables across different branches, you can use dotenvx to securely manage your configurations. This approach is particularly useful for teams working with Git branches and preview deployments.

环境文件结构 #

🌐 Environment file structure

按照示例仓库使用的惯例，环境通过位于 supabase 目录下的 dotenv 文件进行配置：

🌐 Following the conventions used in the example repository, environments are configured using dotenv files in the supabase directory:

文件	环境	`.gitignore` 它吗？	加密
.env.keys	所有	是	否
.env.local	本地	是	否
.env.production	生产	否	是
.env.preview	分支	否	是
.env	任何	也许	是

设置加密密钥 #

🌐 Setting up encrypted secrets

生成密钥对并加密你的秘密：

1
npx @dotenvx/dotenvx set SUPABASE_AUTH_EXTERNAL_GITHUB_SECRET "<your-secret>" -f supabase/.env.preview

这会在 supabase/.env.preview 中创建一个新的加密密钥，在 supabase/.env.keys 中创建一个新的解密密钥。

🌐 This creates a new encryption key in supabase/.env.preview and a new decryption key in supabase/.env.keys.

更新项目密钥：

1
npx supabase secrets set --env-file supabase/.env.keys

在 config.toml 中选择你的配置方式：

选项A：直接使用加密值：

🌐 Option A: Use encrypted values directly:

1
[auth.external.github]
2
enabled = true
3
secret = "encrypted:<encrypted-value>"

选项 B：使用环境变量：

🌐 Option B: Use environment variables:

1
[auth.external.github]
2
enabled = true
3
client_id = "env(SUPABASE_AUTH_EXTERNAL_GITHUB_CLIENT_ID)"
4
secret = "env(SUPABASE_AUTH_EXTERNAL_GITHUB_SECRET)"

秘密的字段

encrypted: 语法只适用于配置中指定的“秘密”字段。在其他字段中使用加密值不会被自动解密，可能会导致问题。对于非秘密字段，请改用带有 env() 语法的环境变量。

🌐 The encrypted: syntax only works for designated "secret" fields in the configuration. Using encrypted values in other fields will not be automatically decrypted and may cause issues. For non-secret fields, use environment variables with the env() syntax instead.

以下字段支持 encrypted: 语法：

🌐 The following fields support the encrypted: syntax:

工作室

studio.openai_api_key

数据库

db.root_key
db.vault.*（保险库地图上的任意键）

认证 - 核心密钥

auth.publishable_key
auth.secret_key
auth.jwt_secret

认证 - 邮件 (SMTP)

auth.email.smtp.pass

认证 - 验证码

auth.captcha.secret

认证 - 钩子

auth.hook.mfa_verification_attempt.secrets
auth.hook.password_verification_attempt.secrets
auth.hook.custom_access_token.secrets
auth.hook.send_sms.secrets
auth.hook.send_email.secrets
auth.hook.before_user_created.secrets

认证 - 短信服务提供商

auth.sms.twilio.auth_token
auth.sms.twilio_verify.auth_token
auth.sms.messagebird.access_key
auth.sms.textlocal.api_key
auth.sms.vonage.api_secret

认证 - 外部 OAuth 提供商

auth.external.*.secret

边缘运行时

edge_runtime.secrets.*（secrets 映射中的任意键）

与预览分支一起使用 #

🌐 Using with preview branches

当你提交包含加密值的 .env.preview 文件时，分支执行器会在部署你的分支时自动获取并使用这些值。这让你可以为不同的分支保持不同的配置，同时确保敏感信息的安全。

🌐 When you commit your .env.preview file with encrypted values, the branching executor will automatically retrieve and use these values when deploying your branch. This allows you to maintain different configurations for different branches while keeping sensitive information secure.

配置示例 #

🌐 Configuration examples

多环境设置 #

🌐 Multi-environment setup

这里有一个完整的多环境配置示例：

🌐 Here's an example of a complete multi-environment configuration:

1
# Default configuration for all branches
2
[api]
3
enabled = true
4
port = 54321
5
schemas = ["public", "storage", "graphql_public"]
6
[db]
7
port = 54322
8
pool_size = 10
9
10
# Staging-specific configuration
11
[remotes.staging]
12
project_id = "staging-project-ref"
13
[remotes.staging.api]
14
max_rows = 1000
15
16
[remotes.staging.db.seed]
17
sql_paths = ["./seeds/staging.sql"]
18
19
# Production-specific configuration
20
[remotes.production]
21
project_id = "prod-project-ref"
22
[remotes.production.api]
23
max_rows = 500
24
25
[remotes.production.db]
26
pool_size = 25

要获取现有分支的项目ID，请使用 branches list 命令：

🌐 To retrieve the project ID for an existing branch, use the branches list command:

1
supabase --experimental branches list

这将显示一个表格，展示你所有的分支以及它们对应的项目 ID。使用 BRANCH PROJECT ID 列的值作为远程配置中的 project_id。

🌐 This will display a table showing all your branches with their corresponding project ID. Use the value from the BRANCH PROJECT ID column as your project_id in the remote configuration.

功能分支配置 #

🌐 Feature branch configuration

对于需要特定设置的功能分支：

🌐 For feature branches that need specific settings:

1
[remotes.feature-oauth]
2
project_id = "feature-branch-ref"
3
[remotes.feature-oauth.auth.external.google]
4
enabled = true
5
client_id = "env(GOOGLE_CLIENT_ID)"
6
secret = "env(GOOGLE_CLIENT_SECRET)"

要获取现有分支的项目ID，请使用 branches list 命令：

🌐 To retrieve the project ID for an existing branch, use the branches list command:

1
supabase --experimental branches list

这将显示一个表格，展示你所有的分支以及它们对应的项目 ID。使用 BRANCH PROJECT ID 列的值作为远程配置中的 project_id。

🌐 This will display a table showing all your branches with their corresponding project ID. Use the value from the BRANCH PROJECT ID column as your project_id in the remote configuration.

下一步 #

🌐 Next steps

探索分支整合
了解一下分支故障排除
查看分支定价