Dart 3.0 已全面移除对非空安全代码的支持,因此项目中的 pubspec.yaml 文件必须将 SDK 约束升级至 >=2.12.0 <3.0.0,并完成完整的空安全迁移流程,否则执行 flutter pub get 时将会失败(例如出现错误码 614)。
Dart 3.0 的发布,标志着一场彻底的转变——它彻底告别了非空安全模式,不再兼容任何未进行空安全迁移的 Dart 代码。简单来说,如果你本地的 Flutter SDK 版本已经是 3.0.0(对应 Dart 3.0),而项目的 `pubspec.yaml` 中声明的 SDK 下限仍低于 2.12.0(比如写着 `>=2.10.0 <3.0.0`),那么在运行 `flutter pub get` 时,编译器会直接报错:
The lower bound of "sdk: '>=2.10.0 <3.0.0'" must be 2.12.0 or higher to enable null safety.
这个错误并非配置语法有误,而是 Dart 工具链中内置的一道强制性校验闸门:Dart 3.0 只认可已启用空安全的代码,而空安全自 Dart 2.12 起便已默认开启且不可绕过。因此,正确的 SDK 约束应修改为:
environment: sdk: ">=2.12.0 <3.0.0" # 注意:下限必须 ≥2.12.0
不过,仅修改 `pubspec.yaml` 还远远不够。`>=2.12.0` 只是为项目提供了一张“空安全许可票”,但代码本身并未真正完成迁移——你还需要执行完整的迁移流程,才能让项目在空安全模式下正常运行。
1. 检查当前迁移状态
首先需要评估迁移范围。运行以下命令,查看哪些文件尚未实现空安全:
dart migrate --show-all
或者在 VS Code 中,右键点击项目根目录,选择 “Dart: Start Null Safety Migration”,效果相同。
2. 分阶段迁移(推荐)
对于大型项目(例如报错中涉及 614 个文件的情况),不要试图一次性强制完成迁移,那样只会让问题更加复杂。关键在于掌握节奏:
- 使用
--skip-imports参数跳过对第三方依赖的分析,先专注于自有代码; - 优先处理核心业务模块,例如
lib/main.dart、lib/models/、lib/services/; - 对每个文件,可临时添加
// @dart=2.12注释作为临时兼容方案,然后逐步修复空值警告; - 善用
!、?、late、required以及可空类型(如String?)来重构逻辑。
3. 验证与清理
迁移完成后,请检查以下三项内容:
- 所有
.dart文件顶部,不得遗留// @dart=2.9这类降级注释; - 在
analysis_options.yaml中,必须启用与空安全相关的 lint 规则(例如unnecessary_null_comparison); - 运行
flutter analyze和flutter test,确保没有任何空安全相关的错误。
重要提醒:
- Flutter 3.10+ 默认绑定 Dart 3.0,该版本组合无法回退到 Dart 2.x;
- 如果第三方依赖包尚未支持空安全,必须将其升级至兼容版本——可前往 pub.dev 查看该包的“Null safety”标签;
- 若某个关键依赖包迟迟不更新(例如其 pubspec.yaml 中仍写着
sdk: ">=2.7.0 <3.0.0"),可以考虑 fork 该仓库,修改其pubspec.yaml并引入本地路径作为临时解决方案。但从长远来看,仍需推动上游维护者发布空安全版本。
完成上述全部流程后,再次执行 flutter clean && flutter pub get,报错 614 便会彻底消失。取而代之的,是一套更加健壮、更利于静态分析的 Dart 3 代码基线。
