Flutter空安全迁移构建失败：FirebaseFirestoreWeb.runTransaction参数不匹配

问题分析 #

核心问题分为两点：

• 编译报错：FirebaseFirestoreWeb.runTransaction 重写父类方法时缺少maxAttempts命名参数，源于web端实现与平台接口版本不匹配。
• 版本解析失败：cloud_firestore ^5.1.0 无匹配版本，说明当前Flutter SDK版本与该依赖不兼容，或依赖链存在冲突。

解决方案 #

1. 适配Flutter SDK与cloud_firestore版本 #

先查看当前Flutter SDK版本：

flutter --version

cloud_firestore ^5.0.0+ 通常要求Flutter SDK ≥3.10.0。若SDK版本过低，先升级：

flutter upgrade

若不想升级SDK，需在pubspec.yaml中降级cloud_firestore到兼容版本（比如SDK在3.7.x时，可尝试^4.8.0），修改后执行：

flutter pub get

2. 修复runTransaction参数缺失问题 #

版本适配后仍报错，大概率是缓存导致web端实现未更新，执行缓存清理：

flutter clean
flutter pub get
flutter pub run build_runner clean # 项目用到build_runner时执行

若你自定义了Firestore web实现类，需手动补充maxAttempts参数：

@override
Future<T> runTransaction<T>(
  TransactionHandler<T> transactionHandler, {
  Duration timeout = const Duration(seconds: 30),
  int maxAttempts = 5, // 补充该参数
}) async {
  // 你的业务实现逻辑
}

3. 强制覆盖依赖版本（可选） #

若依赖链存在冲突，可在pubspec.yaml中添加依赖覆盖，强制使用兼容版本：

dependency_overrides:
  cloud_firestore: ^5.1.0 # 替换为实际兼容的版本号
  cloud_firestore_web: ^5.1.0 # 确保web端版本与核心版本一致

添加后执行flutter pub get，若仍有冲突，通过flutter pub outdated输出逐一调整其他依赖版本。

内容的提问来源于stack exchange，提问作者Asha Chamy