企业官网建设流程全解析

Supabase 怎么用持久化分支（Branching）管理迁移与开发工作流？

【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase

这篇文章解决一个具体任务：在 Supabase 上为项目建一个长期运行的持久化分支（persistent branch），作为 staging / QA / 开发环境，把数据库迁移（migration）和服务配置放进 Git 版本控制，通过 GitHub 集成自动同步到分支上，并在合并回生产前完成验证与回滚。适用前提：你已有一个连接到 GitHub 仓库的 Supabase 项目——Supabase 在任意套餐上都支持直接从 GitHub 部署，Branching 在此之上为每个 pull request 增加隔离的预览环境（参见 Branching 总览）。

持久化分支和预览分支是什么关系

Branching 文档把两种分支区分得很明确：

• 预览分支（Preview branches）：临时性环境，适合聚焦测试，在 PR 合并或关闭时会被自动删除。
• 持久化分支（Persistent branches）：长期运行，文档推荐用于 staging、QA 或 development 环境。它们不会因为不活跃而被自动暂停，也不会在 PR 合并或关闭时被删除。

两者都是从主项目克隆出来的独立环境，有自己的 Supabase 实例和 API 凭据，并且都携带主项目已部署的 Edge Functions 与配置。默认都不带主项目的数据或存储对象（这是为了隔离生产数据），需要数据时可用 seed 文件或 dashboard 的Include data选项补充。

准备条件：连接 GitHub 并初始化 supabase 目录

按 GitHub integration 文档 的顺序执行：

1. 在 Supabase Dashboard 进入Project Settings>Integrations，在GitHub Integration下点击Authorize GitHub，在跳转的页面点击Authorize Supabase。
2. 回到 Integrations 页，选择要连接项目所用的 GitHub 仓库。
3. 设置Working directory：它表示从仓库根目录到包含supabase/文件夹所在目录的路径。supabase/在仓库根目录时填.；例如目录结构是apps/web/supabase/时填apps/web。
4. 点击Enable integration，并启用Automatic branching选项，让 GitHub 分支与 Supabase 分支自动同步（可选启用Supabase changes only，仅当 Supabase 文件变化时才创建分支）。
5. 在 GitHub 仓库设置中为 Supabase 集成开启 required check。这样迁移检查失败时 PR 无法合并，可以阻止无效迁移进入生产分支。

然后初始化仓库中的supabase/目录（如果你还没有该目录）：

# 初始化本地 supabase 目录 supabase init # 拉取数据库迁移。--db-url 需要替换为 Session pooler 连接串， # 在项目 Dashboard 的 Connect 页面获取 supabase db pull --db-url <db_connection_string> # 提交 supabase 目录到 Git git add supabase git commit -m "Initial migration" git push

文档中给出的连接串示例格式如下（仅示例，你的值以 Connect 页面为准）：

postgres://postgres.xxxx:password@xxxx.pooler.supabase.com:5432/postgres

这一步很关键：新分支的数据库 schema 不是克隆出来的，而是由你提交到仓库的迁移文件构建的。migrations子目录中的迁移在分支创建时自动执行，之后的每次提交只会执行尚未应用的迁移。

创建持久化分支并获取它的 project ID

使用 CLI 创建持久化分支（命令来自 Configuration 文档）：

supabase --experimental branches create --persistent # 提示输入分支名，例如： # Do you want to create a branch named develop? [Y/n]

创建后查询分支对应的 project ID：

supabase --experimental branches list

命令输出是一张包含所有分支的表格，BRANCH PROJECT ID列的值就是下一步写入config.toml的project_id。

在 config.toml 中为持久化分支写入配置

config.toml的[remotes]块用于给特定持久化分支设置独立配置。注意顺序限制：project_id必须引用一个已存在的分支，所以要先创建分支，再添加它的配置，这也是上一节先执行branches create的原因。

文档给出的示例是为 staging 环境配置独立的 seed 脚本：

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

其中your-project-ref需替换为branches list输出中该分支的BRANCH PROJECT ID。修改config.toml后推送到 Git，集成会检测到变更并应用到对应分支；[remotes]块中所有标准配置项都可用，包括数据库、API、Auth 和 Edge Functions 配置。有一个明确的失败条件：如果没声明对应 remote、或project_id写错，部署工作流中的配置步骤会被跳过。

敏感配置用 CLI 按分支单独设置：

# 从 .env 文件批量设置 supabase secrets set --env-file ./supabase/.env # 或逐个设置 supabase secrets set SMTP_HOST=smtp.example.com supabase secrets set SMTP_USER=your-username supabase secrets set SMTP_PASSWORD=your-password

然后在config.toml中通过env()语法引用：

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

secrets 是按分支隔离的：为一个分支设置的 secret 不会自动出现在其他分支，需要的分支要分别设置。

日常开发工作流：迁移如何同步到分支

Working with branches 文档给出两种工作流。

本地开发工作流：

1. 为功能创建新的 Git 分支；
2. 使用 Supabase CLI 做 schema 变更；
3. 用supabase db diff生成迁移文件；
4. 本地测试；
5. 提交并推送到 GitHub；
6. 打开 pull request 创建预览分支。

远端开发工作流：

1. 在 Supabase dashboard 创建预览分支；
2. 用顶栏的分支下拉框切换到该分支；
3. 在 dashboard 中做 schema 变更；
4. 本地用supabase db pull拉回变更；
5. 提交生成的迁移文件；
6. 推送到 Git 仓库。

几个影响判断的事实：

• 迁移按顺序执行，每条迁移建立在前面之上；预览分支继承基础项目的迁移历史，只执行尚未跑过的迁移。
• 每个分支有自己的数据库实例、API 端点、Auth 配置和存储桶。切换分支用 dashboard 顶栏的分支下拉框；分支专属的 URL 和 key 在切换到该分支后从Settings > API复制。
• 分支之间完全隔离，一个分支上的 schema、数据、存储对象、Edge Functions、Auth 配置变更不影响其他分支。
• 如果迁移要由自己的 ORM 管理，文档的做法是在 GitHub Actions 中等预览分支就绪后，用supabase --experimental branches get "$GITHUB_HEAD_REF" -o env输出分支凭据，再用psql "$POSTGRES_URL_NON_POOLING"执行迁移；完整 workflow 示例（含SUPABASE_ACCESS_TOKEN、SUPABASE_PROJECT_ID两个 secret 和等待Supabase Previewcheck 的步骤）见 Working with branches 文档。

合并到生产时实际发生什么

把任何分支合并进主项目时，Supabase 自动执行部署工作流，文档将其表示为有向无环图，节点依次为：

1. Clone— 检出指定 git 分支（dashboard 方式创建分支时可选）；
2. Pull— 从主项目拉取数据库迁移（dashboard 方式时同时初始化迁移历史表）；
3. Health— 最长等待 2 分钟，直到 Auth、API、Database、Storage、Realtime 全部健康；
4. Configure— 按config.toml更新服务配置（仅 GitHub 集成方式）；
5. Migrate— 应用待处理的数据库迁移和 vault secrets；
6. Seed— 运行 seed 文件填充初始数据（对持久化分支，必须在config.toml中启用，即上一节的[remotes.<branch>.db.seed]）；
7. Deploy— 部署变更的 Edge Functions 并更新函数 secrets。

父步骤失败时所有依赖它的子步骤会被跳过——例如 Migrate 失败，Seed 不会执行。使用 GitHub 集成时，推送到该 git 分支的每次提交都会重新跑这套工作流。

另外，启用Deploy to production选项后，推送或合并到生产分支时自动部署的变更范围是：新迁移被应用、config.toml声明的 Edge Functions 被部署、config.toml声明的存储桶被部署；API、Auth、seed 等其他配置默认被忽略。

如何验证部署结果与迁移是否正确

• PR 状态：GitHub 集成为 PR 添加部署状态评论，预览分支的部署状态直接可见在 PR 上。
• 分支日志：dashboard 进入Manage Branches，点击分支查看部署日志，View logs区域有详细错误信息。
• 本地预演：迁移文件改动后，文档给出的调试命令是先本地验证再推上去：

# 在本地测试迁移 supabase db reset

• 失败拦截：前面开启的 required check 会在迁移检查失败时阻止 PR 合并；文档还建议订阅分支的邮件通知，常见错误包括迁移冲突、函数部署失败、无效配置文件。
• Webhook（可选）：持久化分支可以订阅 action run 完成后的 webhook 通知（payload 遵循 standard webhooks 标准，事件类型为run.completed），文档给出了把它接到一个 Edge Function 再转发到 Slack 的完整做法，见 Working with branches 文档。

部署失败时按 Troubleshooting 文档 核对三类原因：迁移中的无效 SQL 或 schema 冲突、config.toml配置错误、以及迁移文件依赖的对象不存在或权限问题。迁移顺序类问题（时间戳冲突、Git rebase 后时间戳乱序）的排查方式下一节说明。

回滚迁移与修复顺序问题

撤掉一条不想要的迁移：推送到基础分支时如果带上了不想保留的 schema 变更，做法是推送最新修改后，在 Supabase 中删除该预览分支并重新打开 PR。新预览分支是基础项目的全新克隆，默认从./supabase/seed.sql重新填充；旧预览分支上的额外数据变更会丢失。

重跑基础项目已应用过的迁移：改用 dashboard 对该分支执行 reset。reset 会按顺序重跑所有迁移，并丢弃分支上的现有数据。

rebase 后迁移乱序：迁移按时间戳顺序应用，构建在较早变更之上的迁移必须使用更晚的时间戳。文档给出的修复方式是重命名迁移文件再本地验证：

# 重命名迁移文件以修复时间戳顺序 mv 20240101000000_old.sql 20240102000000_old.sql # 重置本地数据库测试 supabase db reset

多个预览分支之间的 schema 漂移：某个预览分支合并进生产后，与尚未合并的预览分支之间会产生 schema 差异，处理方式与普通 Git 冲突相同——从生产 Git 分支 merge 或 rebase 到预览 Git 分支，并确保 rebase 后迁移文件时间戳正确。

已知限制

• 预览分支数据是临时的：分支删除时数据丢失，数据不会在分支之间迁移，删除重建后数据不保留；分支创建时只 seed 一次，重跑 seed 需要删除并重建分支（关闭再重新打开 PR）。
• 预览分支不活跃后会自动暂停，暂停后的首次请求可能超时，分支会在第一个请求后唤醒；常用分支建议转为持久化分支（持久化分支不会因不活跃被暂停或删除）。
• 通过 dashboard 管理分支目前处于 public alpha，且有明确限制：分支只能合并到 main，不支持预览分支之间互合并；通过 dashboard 创建的自定义角色不会被分支捕获；分支Include data选项要求项目有 Point-in-Time Recovery 附加组件，且分支使用更大磁盘并与项目计算规格一致，会增加成本；功能分支上过期时拉取 main 的变更会覆盖已有 Edge Functions（新创建的函数保留）。
• 不能更改哪个分支充当生产分支——所有分支克隆来源的基础项目永远是生产分支；但可以修改生产分支关联的 GitHub 分支名（在 Integrations 页面）。
• config.toml改了不生效时，文档列出的检查项是：TOML 语法、变更是否已提交并推送、删除并重建分支。

分支的用量与计费细节见 Branching 计费文档；更多故障场景见 Troubleshooting 文档。

【免费下载链接】supabaseThe Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.项目地址: https://gitcode.com/GitHub_Trending/supa/supabase