Skip to content
Home

故障排除

Common issues and solutions for Supabase branching

本指南涵盖了你在使用 Supabase 分支时可能遇到的常见问题以及如何解决它们。

🌐 This guide covers common issues you might encounter when using Supabase branching and how to resolve them.

监控部署 #

🌐 Monitoring deployments

查看部署状态并排查故障：

🌐 To check deployment status and troubleshoot failures:

  1. 去你的项目仪表板
  2. 导航到“管理分支”
  3. 点击你的分支查看部署日志
  4. 查看“查看日志”部分了解详细错误信息

对于程序化监控，你可以使用 管理 API 来轮询分支状态。

🌐 For programmatic monitoring, you can use the Management API to poll branch status.

如需详细故障排除指导，请查看我们的故障排除指南。

🌐 For detailed troubleshooting guidance, see our Troubleshooting guide.

常见问题 #

🌐 Common issues

回滚迁移 #

🌐 Rolling back migrations

你可能想回滚之前迁移中所做的更改。例如，你可能已经推送了一个包含你不再需要的模式更改的迁移文件。

🌐 You might want to roll back changes you've made in an earlier migration change. For example, you may have pushed a migration file containing schema changes you no longer want.

要解决这个问题，先推送最新的更改，然后在 Supabase 中删除预览分支，再重新打开它。

🌐 To fix this, push the latest changes, then delete the preview branch in Supabase and reopen it.

新的预览分支是你基础项目的全新克隆，默认会从 ./supabase/seed.sql 文件重新生成。旧预览分支上的任何额外数据更改都会丢失。

🌐 The new preview branch is a fresh clone of your base project and is reseeded from the ./supabase/seed.sql file by default. Any additional data changes made on the old preview branch are lost.

如果你想重新运行基础项目已经应用的迁移，请改为从 Supabase 控制面板重置分支。重置会按顺序重新运行所有迁移，并清除分支上现有的数据。

🌐 To rerun migrations that your base project has already applied, reset the branch from the Supabase dashboard instead. A reset reruns all migrations in sequential order and drops existing data on the branch.

部署失败 #

🌐 Deployment failures

部署可能会因为各种原因失败，包括无效的 SQL 语句、迁移中的模式冲突、config.toml 配置中的错误，或者其他原因。

🌐 A deployment might fail for various reasons, including invalid SQL statements and schema conflicts in migrations, errors within the config.toml config, or something else.

要查看错误信息，请在 查看日志 部分查看你分支的 Supabase 工作流运行情况。

🌐 To check the error message, see the Supabase workflow run for your branch under the View logs section.

预览分支之间的模式漂移 #

🌐 Schema drift between preview branches

如果存在多个预览分支，每个预览分支可能包含不同的架构更改。这有点像 Git 分支，每个分支可能包含不同的代码更改。

🌐 If multiple preview branches exist, each preview branch might contain different schema changes. This is similar to Git branches, where each branch might contain different code changes.

当一个预览分支被合并到生产分支时，会在生产分支和尚未合并的预览分支之间产生模式漂移。

🌐 When a preview branch is merged into the production branch, it creates a schema drift between the production branch and the preview branches that haven't been merged yet.

这些冲突可以像处理普通 Git 冲突一样解决：从生产 Git 分支合并或变基到预览 Git 分支。由于迁移是按顺序应用的，变基后要确保迁移文件的时间戳正确。基于早期更改的修改应该总是有较晚的时间戳。

🌐 These conflicts can be resolved in the same way as normal Git Conflicts: merge or rebase from the production Git branch to the preview Git branch. Since migrations are applied sequentially, ensure that migration files are timestamped correctly after the rebase. Changes that build on top of earlier changes should always have later timestamps.

如果你使用声明式架构文件来管理你的架构，那么应该在架构文件中解决漂移。删除你分支生成的迁移文件，然后运行 supabase db schema declarative sync 重新生成。重新生成的迁移会有新的时间戳，所以它会在现有迁移之后排序，而无需手动重命名文件。

🌐 If you manage your schema with declarative schema files, resolve the drift in the schema files instead. Delete the migrations your branch generated, then run supabase db schema declarative sync to regenerate them. The regenerated migration gets a new timestamp, so it orders after existing migrations without renaming files by hand.

正在切换生产分支 #

🌐 Changing production branch

你无法更改哪个项目分支作为生产分支——所有分支创建自的基础项目分支将始终保持为生产分支。不过，你可以更新哪个 GitHub 分支与你的生产分支关联。要做到这一点，去 Integrations 页面 并更改生产分支的名称。

🌐 You cannot change which project branch serves as the production branch — the base project that all branches are created from will always remain the production branch. However, you can update which GitHub branch is linked to your production branch. To do this, go to the Integrations page and change the production branch name.

迁移问题 #

🌐 Migration issues

迁移失败 #

🌐 Failed migrations

当迁移失败时，检查：

🌐 When migrations fail, check:

  1. SQL 语法：确保你的迁移文件包含有效的 SQL
  2. 依赖：检查迁移是否依赖不存在的对象
  3. 权限：确认迁移不需要超级用户权限

调试：

🌐 To debug:

# Test migrations locally first
supabase db reset
# Check migration logs in the dashboard
# Navigate to Branches > Your Branch > View Logs

在新分支上出现权限被拒绝的错误 #

🌐 Permission denied errors on a new branch

如果数据 API 在某个分支上对你的基础项目中的表或函数返回 42501 权限拒绝错误，这意味着该分支缺少对 public 模式的默认权限。新分支创建时不会有这些权限，只有你的迁移可以把它们重新授予回来。

🌐 If the Data API returns 42501 permission denied errors on a branch for tables or functions that work on your base project, the branch is missing default privileges on the public schema. New branches are created without them, and only your migrations can grant them back.

检查你的初始迁移是否包含 public 模式的 alter default privileges ... grant 语句。如果没有，请参阅 分支的默认权限 了解如何添加它们，或者在迁移中 显式授予访问权限。

🌐 Check whether your initial migration contains alter default privileges ... grant statements for the public schema. If it doesn't, see Default privileges on branches for how to add them, or grant access explicitly in a migration.

迁移订单问题 #

🌐 Migration order problems

迁移必须按正确的顺序运行。常见问题：

🌐 Migrations must run in the correct order. Common issues:

  1. 时间戳冲突：确保迁移文件具有唯一的时间戳
  2. 依赖问题：后续迁移依赖于之前的迁移
  3. Rebase 问题：Git rebase 后时间戳顺序错乱

修复方式：

🌐 Fix by:

# Rename migration files to fix timestamp order
mv 20240101000000_old.sql 20240102000000_old.sql
# Reset local database to test
supabase db reset

在单次由 pg-delta 引擎（supabase db diff 或 db schema declarative sync）生成的迁移中，你不需要手动重新排列语句，因为引擎会按依赖自动排序。单独生成的迁移，例如在两个分支上生成后再合并的迁移，仍然需要正确的相对时间戳，所以请像上面显示的那样重命名或重新生成它们。一次同步也可能会写入共享名称的拆分文件（_1/_2 后缀），它们的时间戳相差一秒。CLI 会按时间戳顺序应用它们，所以如果你重命名拆分文件中的一个而改变了顺序，会破坏执行序列。应该重新生成迁移。参考 清理生成的迁移。

🌐 Within a single migration generated on the pg-delta engine (supabase db diff or db schema declarative sync), you don't need to reorder statements by hand, because the engine orders them by dependency. Migrations generated separately, such as on two branches that later merge, still need correct relative timestamps, so rename or regenerate them as shown above. A single sync can write split files that share a name (_1/_2 suffixes) with timestamps one second apart. The CLI applies them in timestamp order, so renaming one file of a split pair in a way that changes that order breaks the sequence. Regenerate the migration instead. See Cleaning up generated migrations.

连接问题 #

🌐 Connection issues

无法连接到预览分支 #

🌐 Cannot connect to preview branch

如果你无法连接到预览分支：

🌐 If you can't connect to a preview branch:

  1. 检查凭证：确保你使用的是正确的分支专用凭证
  2. 自动暂停：该分支可能已暂停。它将在第一次请求时恢复
  3. 网络限制：检查是否有网络限制阻止访问

连接超时 #

🌐 Connection timeouts

预览分支在不活动后会自动暂停。暂停后的首次连接可能会超时：

🌐 Preview branches auto-pause after inactivity. First connections after pause may timeout:

  1. 重试：分支将在第一次请求后唤醒
  2. 持久分支：将常用分支转换为持久分支

配置问题 #

🌐 Configuration problems

Config.toml 没有生效 #

🌐 Config.toml not applying

如果配置更改没有生效：

🌐 If configuration changes aren't applying:

  1. 语法错误：验证你的 config.toml 语法
  2. Git 同步：确保更改已提交并推送
  3. 分支刷新：试着删除并重新创建分支

秘密不可用 #

🌐 Secrets not available

如果你的分支上的密钥不起作用：

🌐 If secrets aren't working in your branch:

  1. 分支专用：记住秘密是针对每个分支设置的
  2. 语法：使用正确的语法：env(SECRET_NAME)
  3. CLI 版本：确保你使用的是最新的 CLI 版本

性能问题 #

🌐 Performance issues

创建分支慢 #

🌐 Slow branch creation

创建分支可能会很慢，因为：

🌐 Branch creation might be slow due to:

  1. 大型迁移：许多或复杂的迁移文件
  2. 种子数据：大型种子文件处理起来需要时间
  3. 网络延迟：与分支区域的地理距离

查询性能 #

🌐 Query performance

预览分支可能有不同的性能表现：

🌐 Preview branches may have different performance characteristics:

  1. 冷启动：自动暂停后的首次查询会比较慢
  2. 资源限制：预览分支有不同的资源分配
  3. 索引：确保你的迁移中存在合适的索引

数据问题 #

🌐 Data issues

种子数据未加载 #

🌐 Seed data not loading

如果种子数据没有加载：

🌐 If seed data isn't loading:

  1. 文件位置：确保 seed.sql 在 ./supabase/ 目录下
  2. SQL 错误：检查种子文件中的语法错误
  3. 依赖：种子数据可能会引用不存在的表

数据持久化 #

🌐 Data persistence

记住预览分支的数据：

🌐 Remember that preview branch data:

  1. 是临时的：分支删除时数据会丢失
  2. 未迁移：数据不会在分支之间移动
  3. 在重新创建时重置：删除并重新创建分支会导致数据丢失

获取帮助 #

🌐 Getting help

如果你仍然有问题：

🌐 If you're still experiencing issues:

  1. 查看日志：在仪表板中查看分支日志
  2. 社区：在 GitHub 讨论 中提问
  3. 支持：如有项目相关问题，请联系支持
  4. 文档：查看最新文档以获取更新