Why are my Supabase branches empty?

Supabase 的分支（Branching 2.0）在从 main 创建环境时依赖你项目中的当前迁移文件——而不是模式转储。这意味着如果你的 main 分支缺少迁移历史，分支操作将无法完全捕获你的模式。这是 Branching 2.0 文档 中提到的一个已知限制。请按照以下步骤生成、同步并修复你的迁移历史，以便顺利进行分支操作。

🌐 Branching in Supabase (Branching 2.0) relies on the current migration files in your project—not a schema dump—when creating environments from main. This means if your main branch lacks migration history, branching will not fully capture your schema. This is a known limitation highlighted in the Branching 2.0 documentation. Follow the steps below to generate, synchronize, and repair your migration history for smooth branching.

1. 前提条件：准备本地 Supabase 环境 #

🌐 1. Prerequisites: Prepare local Supabase environment

• 如果你还没有本地环境，可以按照 Supabase 本地开发入门指南操作：
  • 在本地运行 Supabase。

执行以下命令来初始化并启动本地项目：

🌐 Execute the following commands to initialize and start a local project:

1
supabase init
2
supabase start

2. 把远程 schema 拉进迁移里 #

🌐 2. Pull remote schema into migrations

在你的项目关联后，运行：

🌐 With your project linked, run:

1
supabase db pull --linked

这个命令会在你的 supabase/migrations 文件夹里生成一个迁移文件，反映你的远程架构。它不会在本地运行迁移，也不会覆盖任何东西。

🌐 This command generates a migration file in your supabase/migrations folder which reflects your remote schema. This will not run the migration locally or overwrite anything.

3. 同步远程迁移历史 #

🌐 3. Sync remote migration history

运行上述命令后，Supabase CLI 通常会提示：

🌐 Upon running the above command, the Supabase CLI will typically prompt with:

1
Update remote migration history table? [Y/n]

输入 Y 来更新你远程项目的迁移历史，并确保它与你新的本地迁移一致。

🌐 Type Y to update your remote project’s migration history and ensure it matches your new local migrations.

如果命令行提示因为不匹配而建议修复迁移历史，你可能会看到：

🌐 If the CLI suggests repairing migration history due to mismatches, you might see:

1
Make sure your local git repo is up-to-date. If the error persists, try repairing the migration history table:
2
supabase migration repair --status applied TIMESTAMP_OF_MIGRATION_TO_REPAIR

运行提供的修复命令，按说明替换时间戳（示例时间戳：20251006141726）。这会同步本地和远程的迁移状态。

🌐 Run the exact repair command provided, replacing the timestamp as instructed (example timestamp: 20251006141726). This synchronizes the migration state between local and remote.

4. 继续分支 #

🌐 4. Proceed with Branching

一旦你的迁移历史更新完毕，就可以像平常一样继续使用分支功能。每个新分支现在都会继承你 main 分支的正确迁移记录。

🌐 Once your migration history is up to date, continue to use branching features as normal. Each new branch will now inherit the correct migrations from your main branch.

额外小贴士 #

🌐 Additional tips

如果出现更多问题（比如模式漂移或迁移不匹配），请查看故障排除文档，并考虑使用supabase migration repair进行手动修复。

🌐 If further issues arise (such as schema drift or migration mismatches), review the troubleshooting documentation, and consider manual repair with supabase migration repair.