Supabase Multi-Environment Setup 是一个用于在多环境场景下配置 Supabase 的技能，目标是建立开发（local dev）、预发布（staging）和生产（production）三层架构，每个环境对应独立的 Supabase 项目，拥有各自的 URL、API 密钥、数据库、存储和 RLS 策略。该技能通过共享迁移、环境专属密钥以及安全迁移推广，帮助避免跨环境误操作。
【用途】 该技能适用于以下情况：搭建带多环境的新项目；将单项目配置迁移为多环境；在已有 dev/prod 拆分的基础上新增 staging；或配置带数据库分支的预览环境。
【主要能力】
- 三套隔离的 Supabase 项目：每个环境拥有独立的 URL、API 密钥、数据库与存储。
- 环境专属 .env 文件：提供 .env.local、.env.staging、.env.production，其中仅 .env.local 可安全提交。
- 环境感知的 createClient：自动从环境变量构建浏览器客户端（anon key，遵守 RLS）与服务端客户端（service-role key，绕过 RLS），并通过 x-environment 请求头进行追踪。
- 生产环境保护：通过 requireNonProduction() 等守卫，阻止在本地/预发布之外执行破坏性操作，例如种子数据写入与数据库重置。
- 迁移推广流水线：使用 supabase db push 将 schema 变更从本地推广到预发布，再到生产。
- 数据库分支：Pro 计划下通过 supabase branches create 为每个功能提供隔离的数据库、URL 和密钥，用于预览环境。
- CI/CD 工作流：通过 GitHub Actions 按环境部署迁移和 Edge Functions，并为生产环境设置审批门。
- TypeScript 类型生成：可基于本地或已链接项目的 schema 生成 database.types.ts。
【使用方式】 流程分为三步：
- 环境文件与项目布局：保持一个 Supabase CLI 项目，共享 migrations 目录，每个环境一个 .env.* 文件。CLI 一次只链接一个项目，在执行 db push 或 functions deploy 前需重新链接目标项目：npx supabase link --project-ref <target-ref>。
- 环境感知客户端与安全防护：检测一次当前环境，再据此构建浏览器与服务端客户端；所有破坏性辅助函数都需经过生产环境守卫，例如：
export function requireNonProduction(operation: string): void {
if (isProduction()) {
throw new Error([BLOCKED] "${operation}" is not allowed in production.);
}
}
- 迁移推广与数据库分支：严格按照本地 → 预发布 → 生产的顺序推广 schema 变更。db reset 在本地应用全部迁移加种子数据；db push 只将新迁移应用到已链接的远程环境：
npx supabase db reset # 本地：全部迁移 + 种子 npx supabase link --project-ref <staging-ref> && npx supabase db push # 然后预发布 npx supabase link --project-ref <prod-ref> && npx supabase db push # 然后生产
完整示例从初始化到生产推送的命令序列为：
npx supabase init && npx supabase start # 本地，将密钥复制到 .env.local npx supabase migration new create_users # 编写 schema，然后： npx supabase db reset # 本地验证 npx supabase link --project-ref "<staging-ref>" && npx supabase db push npx supabase link --project-ref "<prod-ref>" && npx supabase db push
【适用场景与限制】
- 前置条件：需在 supabase.com/dashboard 创建三个独立 Supabase 项目（dev、staging、production）；安装 Supabase CLI（npm install -g supabase 或 npx supabase --version）；项目安装 @supabase/supabase-js v2+；Node.js 18+ 且所用框架支持 .env 文件（Next.js、Nuxt、SvelteKit 等）；CI 需有密钥管理方案（GitHub Actions Secrets、Vercel 环境变量等）。
- 数据库分支功能需要 Supabase Pro 计划，并在项目设置中启用；免费计划不支持。
- 该技能文档还列出常见错误与处理：如未链接项目导致“Cannot find project ref”，需先执行 supabase link；重复迁移需检查 supabase_migrations.schema_migrations 表；数据库密码错误导致“Permission denied for schema public”，需核对 SUPABASE_DB_PASSWORD；在生产环境误执行 db reset 会导致种子数据进入生产，应改用 db push；环境密钥不匹配需检查 SUPABASE_ENV 与项目 ref；迁移漂移需始终先经预发布推广并用 supabase migration list 对比；类型生成不匹配需从本地（--local）或重新链接规范环境后再生成。
- 文档提到相关后续主题：跨环境认证模式见 supabase-auth-storage-realtime-core，RLS 策略测试见 supabase-policy-guardrails，本地开发流程优化见 supabase-local-dev-loop，监控与可观测性见 supabase-observability。
【输出】 完成该技能后预计产出：三个隔离的 Supabase 项目；环境专属 .env 文件；环境感知的 createClient；生产环境安全防护；迁移推广流水线；数据库分支；CI/CD 工作流；以及生成的 TypeScript 类型文件 database.types.ts。