CentOS 下 Flutter 版本升级注意事项
一 升级前检查与准备
- 确认当前版本与渠道：执行 flutter --version、flutter channel，建议优先在 stable 渠道升级，避免 master/dev 的不稳定变更引入风险。升级前先跑一遍 flutter doctor -v，记录 Android/iOS/Web 等工具链状态，便于升级后逐项核对。若此前为国内镜像加速做过定制（例如在 SDK 内修改了 Gradle 镜像或文件），升级前先还原这些改动，避免执行 flutter upgrade 时出现 “local changes would be overwritten” 的合并冲突。必要时清理缓存后再切换渠道与升级。以上做法能显著降低升级中断与构建异常的概率。
二 正确的升级操作路径
- 推荐的标准流程：在用户目录的 Flutter SDK 中执行 git pull 同步远端；如需指定版本，可先切到目标 channel 或直接使用 flutter upgrade ；升级完成后运行 flutter doctor 校验环境，并用 flutter --version 验证结果。若遇到因本地修改导致的更新失败，先还原修改（或清理相关缓存目录），再切换 channel 后执行升级，可提升成功率。
三 降级与回退方案
- 当升级后出现插件/构建不兼容，需要回退时：在 Flutter SDK 根目录通过 git log 或 GitHub 查找目标版本的 commitId，执行 git reset --hard 回退到该提交；随后运行 flutter doctor 检查环境一致性，并用 flutter --version 确认版本号。回退属于高风险操作，务必先备份项目与 pubspec.lock，并在独立分支验证。
四 Android 构建链与多平台注意事项
- Android 端常见联动变更：升级后需确保 Kotlin 与 AGP（Android Gradle Plugin）/Gradle 的版本匹配，例如升级到 Flutter 2.10 时通常要求 Kotlin ≥ 1.5.31、AGP ≥ 4.0.0 且 Gradle ≥ 6.1.1；同时检查 Android SDK cmdline-tools 与 Build Tools/NDK 是否满足新版本要求。iOS 端（如在 CentOS 上通过远程构建）需确保 CocoaPods 与 Xcode 命令行工具匹配。跨平台项目还要留意插件对 Dart/Flutter 版本的约束，必要时先升级关键插件以避免 API 不兼容。
五 依赖与空安全的处理
- 升级后常见的问题是依赖冲突与空安全迁移：若插件声明了与当前 Flutter/Dart 不兼容的版本范围，需在 pubspec.yaml 中调整依赖并使用 flutter pub get 重新获取；如存在间接依赖冲突，可短期使用 dependency_overrides 绕过，但应作为临时方案并尽快推动插件升级。若项目仍需过渡期，可先维持较低 Dart SDK 约束以完成其他适配，再逐步开启 null safety；也可使用 dart migrate 辅助迁移，结合代码审查与单测回归确保行为一致。