如何正确升级迁移废弃3年的Flutter旧项目至最新版本？

1. 先建立过渡基线，避免一步到位的混乱 #

不要直接升级到最新版，先把项目迁移到支持空安全的最低Flutter/Dart版本（Flutter 2.10.x + Dart 2.12.x），这是空安全迁移的关键过渡节点：

• 修改pubspec.yaml的environment字段：

  environment:
    sdk: ">=2.12.0 <3.0.0"
    flutter: ">=2.10.0"
  

• 执行flutter pub get，先解决基础版本兼容问题。

2. 逐个处理依赖，拒绝批量升级 #

直接用flutter pub upgrade --major-versions会导致依赖冲突集中爆发，正确的做法是逐个处理：

• 逐个检查pubspec.yaml中的依赖：
  • 确认依赖的最新稳定版是否支持空安全（查看依赖的官方文档或版本说明）
  • 已废弃的依赖，寻找功能对等的维护中替代包
  • 无空安全的依赖，优先找社区维护的fork版本，或临时用dependency_overrides强制兼容（后续需替换）
• 每次只升级一个依赖的大版本，执行flutter pub get并编译验证，逐步解决依赖冲突。

3. 空安全迁移（替代已移除的dart migrate） #

Dart 3移除了dart migrate，但可以通过以下方式完成空安全适配：

• 先执行dart fix --apply，自动修复大量语法层面的空安全问题（比如补全?或!）
• 手动处理剩余错误：
  • 按IDE提示逐个修复空值相关问题，优先用null判断（if (x != null)）而非强制解包（!），避免运行时崩溃
  • 执行dart analyze扫描项目，定位所有潜在的空安全隐患并修复

4. 逐步迭代到最新版本 #

当项目在Dart 2.12+环境下能正常编译运行后，再分阶段升级到最新版：

• 先升级到Flutter 3.x初始稳定版（如3.0.x），更新environment字段：

  environment:
    sdk: ">=2.17.0 <4.0.0"
    flutter: ">=3.0.0"
  

• 执行flutter pub upgrade，处理新版本的API变更（如组件改名、参数调整）
• 最后升级到当前最新稳定版，重复上述验证步骤，确保每一步都能正常运行。

5. 验证与兜底测试 #

• 每次升级后，优先运行flutter test（如有测试用例），确保核心逻辑正常
• 手动测试主要页面和交互，排查API变更导致的隐性bug
• 用flutter doctor检查环境，确保工具链配置完整

内容的提问来源于stack exchange，提问作者Nimpô