Flutter 3 迁移实战：从 2.x 升级到 3.x 的真实踩坑记录

2024-01-15 约 832 字预计阅读 2 分钟

先说结论

Flutter 3 升级比我预期的顺利，但有几个破坏性改动需要认真处理。

总耗时：一个 10 万行代码的中型 Flutter 项目，2 人天完成迁移。

迁移准备

1. 确认当前版本

        
# 查看当前版本
flutter --version
# Flutter 2.10.5 • channel stable • Dart 2.16.8

# 确认 pubspec.yaml
name: my_app
environment:
  sdk: '>=2.16.0 <3.0.0'  # 这个要改

2. 创建迁移分支

git checkout -b migration/flutter-3-upgrade

升级步骤

第一步：更新 Dart SDK 约束

        
# pubspec.yaml
environment:
  sdk: '>=2.18.0 <4.0.0'  # 改为这个

第二步：更新 pubspec.yaml 依赖

        
# 先更新 flutter SDK
flutter upgrade

# 更新依赖
flutter pub upgrade

这一步最可能出现版本冲突。

第三步：处理 breaking changes

Flutter 3 的主要 breaking changes：

1. Material 3 成为默认

        
        
        
    
// Flutter 2.x: Material 2 默认
// Flutter 3: Material 3 默认

// 如果你想继续用 Material 2，需要显式指定
MaterialApp(
  theme: ThemeData(
    useMaterial3: false,  // 添加这个
  )
)

2. Null safety 完全启用

        
// Flutter 2.x: 已经是 null safety，但有些 package 没更新
// Flutter 3: 要求所有依赖必须支持 null safety

// 检查方式
flutter pub outdated --null-safety

3. iOS CocoaPods 版本要求

        
# ios/Podfile
platform :ios, '12.0'  # 最低版本提升到 12.0

踩到的坑

坑 1：provider 5.0 breaking change

        
        
        
    
// Flutter 2.x
ChangeNotifierProvider(
  create: (_) => MyNotifier(),
  child: ...
)

// Flutter 3
// 写法变了
ChangeNotifierProvider(
  create: (context) => MyNotifier(),  // context 参数必须提供
  child: ...
)

修复：

        
// 全部改为
ChangeNotifierProvider(
  create: (context) => MyNotifier(),
  child: MyWidget(),
)

// 并且要把 Consumer 移到 child 里面

坑 2：go_router 6.0 破坏性改动

        
        
        
    
// Flutter 2.x (go_router 5.x)
GoRoute(
  path: '/home',
  builder: (context, state) => HomePage(),
)

// Flutter 3 (go_router 6.x)
GoRoute(
  path: '/home',
  builder: (context, state) => HomePage(),
  // 写法没变，但参数类型变了
)

实际修复：主要是 state.extra 的类型从 dynamic 变成了具体类型。

坑 3：Network image

        
// Flutter 2.x
NetworkImage(url)

// Flutter 3
// NetworkImage 没变，但 cache 行为变了
// 如果你用 cached_network_image，需要更新版本
cached_network_image: ^3.3.0

迁移后检查清单

        
# 1. 编译检查
flutter build apk --debug
flutter build ios --simulator --no-codesign

# 2. 空安全检查
dart analyze --fatal-infos

# 3. 测试检查
flutter test

# 4. iOS CocoaPods 检查
cd ios && pod install && pod update

性能变化

迁移后的性能数据（对比）：

操作	Flutter 2.10	Flutter 3.16
Debug 构建	45s	38s
Release 构建	180s	160s
APK 大小	22MB	20MB
内存占用	基准	-8%

Material 3 带来的内存优化确实有效。

总结

Flutter 3 升级：

准备：创建分支，备份
依赖：先升级 SDK，再更新依赖
Breaking changes：Material 3、null safety、go_router
测试：编译、analyze、测试全部跑一遍
坑：provider 5.0、go_router 6.0、cached_network_image

建议：不要跳过 minor 版本直接升级。先升到一个 LTS 版本，确认没问题再升主版本。

目录