用途:将 Dart 或 Flutter 项目从 Supabase v2 迁移到 v3,包括 gotrue、realtime_client、storage_client、functions_client 等已重命名包的处理。完整迁移指南位于 references/migration-v2-v3.md,其章节标题即变更的符号名,可据编译器错误中的符号检索对应章节,其中 Before/After 片段为权威依据。
主要能力:按顺序执行迁移步骤并做完整性检查;要求不手写表定义,类型来自 supabase gen types --lang dart 且生成文件不得编辑;除第 8 步列出的例外,所有查询最终都落到类型化 table() API,并需向用户报告每个例外;保持应用行为不变,v3 改变默认值时显式固定 v2 行为,除非用户要求新行为;不得通过抑制分析器错误或警告来获得干净运行,必须修复;遇到会改变运行时行为且指南未覆盖的选择需先询问用户。
使用方式:1)预检:读取 pubspec.yaml 记录 supabase_flutter、supabase、gotrue、postgrest、realtime_client、storage_client、functions_client 的依赖与版本;运行 git status,工作区不干净时请用户先提交或暂存;运行 dart analyze 保存基线;检查是否存在含 config.toml 与 migrations/ 的 supabase/ 文件夹。2)确认 Supabase CLI 3.0.0 或更新版本,通过 npm 运行则检查 npx supabase --version;版本不足时按平台给出升级命令(Homebrew:brew upgrade supabase/tap/supabase;npm:npm install --save-dev supabase@latest;Scoop:scoop update supabase;未安装参考官方文档),不得在旧版 CLI 上继续或回退到手写类型。3)仍在 v2 时固定 order() 变更的默认值:用 grep -rnE '.order(' lib test bin 查找,无 ascending: 的调用在 v2 为降序、v3 为升序,需加 ascending: false;降序查询在 v2 将 NULL 放最后、v3 放最前,可空列需加 nullsFirst: false(stream().order() 不接受空值位置)。4)更新依赖到各包最新 3.x 版本(dart pub outdated 可列出,含预发布版);supabase 升至 3.x;重命名直接依赖及导入:gotrue→supabase_auth、realtime_client→supabase_realtime、storage_client→supabase_storage、functions_client→supabase_functions,仅重复 supabase 已再导出的直接依赖可移除;添加生成器 dart pub add dev:supabase_typegen 并运行 dart pub get;生成 schema:有 migrations 的 supabase/ 文件夹则 supabase start(需 Docker)后运行 supabase gen types --lang dart,已 supabase link 的项目用 --remote,否则询问项目 ref 用 --remote=<ref>;询问应用查询哪些 schema,public 之外的每个 schema 传 --schema;输出到 lib/supabase_schema.g.dart(除非项目已有生成代码约定);对生成文件运行 dart analyze 必须干净,否则报告错误而非编辑文件。5)机械重命名:按参考中“客户端包重命名”(导入及 GoTrue* 类型名,如 GoTrueClient→AuthClient)、“公共 API 缩写拼写完整”(如 queryParams:→queryParameters:、opts:→options:)、“复数枚举名单数化”、“所有排序方向共用一个 SortDirection”、“所有弃用 API 移除”(如 User.confirmedAt→User.emailConfirmedAt、AuthUser→User)执行。6)编译器驱动修复:运行 dart analyze,对每个新错误在参考中检索其符号并应用 After 形式,重复直到只剩基线问题;常见章节包括 signInWithPassword() 等直接返回 Session、AuthState 为密封类、User.appMetadata 为 AppMetadata 且 userMetadata 永不为 null、Realtime 监听回调改为流、auth 客户端自行持久化会话(localStorage: 与 LocalStorage 子类改为 AuthAsyncStorage)、服务异常共享基类与 FunctionsException 为密封类、每个客户端接受一个 SupabaseRetryOptions、时间戳为 DateTime、rpc 为 getter、insert()/upsert() 不再接受过滤器、rest 客户端及其构建器无状态。7)编译器无法捕获的变更:逐项按给定模式搜索、阅读每个匹配并修复或确认,记录无法决定的站点;涵盖 order() 默认值、RealtimeClient.connectionState 改为类型化(与 SocketState.open 等比较,优先 isConnected)、HttpMethod 为共享枚举(持久化名称而非 index)、确认邮箱或手机变更发出 userUpdated、AuthChangeEvent.initialSession 发给每个订阅者、无 asyncStorage 的客户端将 pkce verifier 保存在内存、各客户端重试退避默认值相同、rest 客户端及构建器无状态(无 select() 的写操作解析为 void)、userMetadata 永不为 null、PostgresChangePayload.errors 为 List<String>、SupabaseClient 自建默认 HTTP 客户端(改用 httpClient:)、Supabase URL 必须用 https(回环地址除外或传 allowInsecureHttp)、无响应请求抛传输异常(捕获 SupabaseTransportException)、accessToken 回调失败抛 AccessTokenException、请求超时限制空闲时间(需总截止时间时在构建器上加 .timeout(…))、Realtime 抛异常而非字符串(捕获 StateError、RealtimeApiException 或 RealtimeTransportException)、登出移除所有频道(需在 AuthSignedOut 后重新订阅)、独立客户端跨标签页会话同步需显式开启(Web 上传 persistSession: true)。8)将每个查询迁移到类型化 table() API:按参考“Moving from from() to the typed table API”逐表转换,每表后重跑 dart analyze;生成文件命名规则:public 中表 books 为 Books、BooksRow、BooksInsert、BooksUpdate,其他 schema 带前缀如 inventory.books 为 InventoryBooks,supabase.schema('inventory').from('books') 变为 supabase.table(InventoryBooks.table),列为表类上的 camelCase 常量如 Books.authorId;转换规则包括方向固定(ascending: false→.desc(),nullsFirst: false→.nullsLast(),两者皆无则保持普通列即升序;类型化 stream() 接受相同排序但对 .nullsFirst()/.nullsLast() 抛 ArgumentError)、类型化 update()/delete() 在 .where(…) 或 .all() 前不发送任何内容(裸 await 可编译但静默无操作,分析器报 unused_result 警告,须全部修复)、Insert/Update 类型省略参数即省略列而传 null 写 SQL NULL、insertAll()/upsertAll() 对仅部分行省略的列使用数据库默认值(无类型列表 insert() 写 NULL)且不接受 defaultToNull、用 row.title 替换 row['title'] as String、仅镜像表的模型类由生成行类型替代、有行为的模型从行 getter 构建而非 toJson()、无类型方法的操作符用 Books.title.raw('eq.Dune')、JSON 路径过滤用 Books.metadata.jsonText('edition').eq('first');from() 与无类型 rpc('fn', params: …) 仅保留用于:生成文件中缺失的表/视图/函数(schema 未生成或未通过 Data API 暴露)、运行时计算的表名、生成器未给方法的函数(生成文件注释中说明)。9)验证与报告:dart analyze 除基线外无问题;对每个改动文件运行 dart format(不格式化已格式化的 lib/supabase_schema.g.dart);运行 dart test,修复迁移导致的失败并报告其余;向用户简要总结依赖变更、生成 schema 文件与命令、第 7 步中需人工决定的每个站点、每个剩余 from() 或无类型 rpc() 调用及原因,以及数据库 schema 每次变更(迁移或仪表盘)后及升级 supabase_typegen 或 Supabase CLI 后须用同一命令重新生成 schema。
适用场景:Dart/Flutter 项目从 Supabase v2 升级到 v3 的迁移工作。
限制:需 Supabase CLI 3.0.0 或更新版本;本地生成需 Docker;不得手写或编辑生成类型文件;不得抑制分析器错误或警告;行为变更需用户确认;部分内容(如具体收费、价格、平台支持范围)资料未提供。