作为Flutter开发者，版本升级是必经之路。本文以实战经验为基础，手把手带你完成将基于Flutter 2.17以及3.4.3的老旧项目平滑升级到3.38.5最新版本，避开90%开发者踩过的深坑！

一、开发依赖环境升级

首先升级 Flutter SDK、依赖的开发工具 Android Studio、Xcode版本以满足开发要求，这点就啥好介绍的。

flutter --version            

Flutter 3.38.5 • channel stable • https://github.com/flutter/flutter.git
Framework • revision f6ff1529fd (12 天前) • 2025-12-11 11:50:07 -0500
Engine • hash c108a94d7a8273e112339e6c6833daa06e723a54 (revision 1527ae0ec5) (12 days ago) • 2025-12-11 15:04:31.000Z
Tools • Dart 3.10.4 • DevTools 2.51.1

二、利用AI辅助升级项目配置

提前做好项目版本记录，千万别忘了。

Prompt：

读取本项目信息，将项目升级适配到flutter最新版本3.38.5, 对项目工程进行修改配置

AI对以下文件进行了修改:

• pubspec.yaml

• android/build.gradle

• gradle-wrapper.properties

• android/app/build.gradle

• Podfile

• AppFrameworkInfo.plist

• Info.plist

对应的修改内容如下：

1、pubspec.yaml

# flutter 依赖SDK进行升级
# 旧版本信息：sdk: ">=2.17.0 <3.0.0" 
sdk: ">=3.0.0 <4.0.0"

dependencies:
	cupertino_icons: ^1.0.2     -> 1.0.8
  shared_preferences: ^2.0.15 -> ^2.0.2
  ... 省略其他包
  
dev_dependencies:
	flutter_lints: ^2.0.0 -> ^3.0.1

这里flutter_lints最新版本的6.0.0, shared_preferences的最新版本是2.5.4，我将这两块升级到最新版本也能正常运行，所以AI生成的版本不一定是最新的，也不一定准确，packages的升级还是采用Flutter提供的命令进行更新升级。

# 查看那些过时了的 package 依赖以及获取更新建议
flutter pub outdated

# 所有依赖更新到 最新的兼容版本
flutter pub upgrade

# 所有依赖更新到 最新的版本
flutter pub upgrade --major-versions

2、安卓这边就是修改了一些依赖的kotlin版本、gradle版本、Java版本等信息具体就不贴出来了

3、iOS这边就是修改了Podfile里面限制的最低版本信息、iOS要求的UIkit生命周期迁移配置等

# Podfile
platform :ios, '12.0'

# AppFrameworkInfo.plist
<key>MinimumOSVersion</key>
<string>12.0</string>

# info.plist   UIKit生命周期迁移修改
<key>UIApplicationSceneManifest</key>
	<dict>
		<key>UIApplicationSupportsMultipleScenes</key>
		<false/>
		<key>UISceneConfigurations</key>
		<dict>
			<key>UIWindowSceneSessionRoleApplication</key>
			<array>
				<dict>
					<key>UISceneConfigurationName</key>
					<string>Default Configuration</string>
					<key>UISceneStoryboardFile</key>
					<string>Main</string>
				</dict>
			</array>
		</dict>
	</dict>
	

考虑到项目情况以及SceneDelegate版本要求，我的项目最低限制并没有采用AI生成的，后面手动修改为要求最低13起了。

三、Dart层代码的修改

这一步比较简单利用开发工具以及Dart Analysis提示对代码进行升级修改，满足最新版本的要求即可。

一般问题都是语法的优化、函数返回值的警告等等。

四、iOS原生方面的升级处理

根据官方3.38.5发布的版本文档以及Apple最新要求需要对UIScene生命周期进行支持，否则后续无法启动应用。

对基于Flutter SDK 2.17.0 开发的项目进行升级，是无法自动迁移的。

对基于Flutter SDK 3.4.3 开发的项目进行升级，项目会自动增加UIScene生命周期进行支持，自动升级iOS最低版本限制和配置info.plist文件

# Flutter SDK 3.4.3开发的项目 会自动适配
ios/Runner/AppDelegate.swift uses the deprecated @UIApplicationMain attribute, updating.
.gitignore does not ignore Swift Package Manager build directories, updating.

4.1 自动迁移

对2.17.0开发的项目进行自动升级，根据官方文档在项目根目录自动迁移，执行以下命令，但是尝试下来是无法自动迁移的。

flutter config --enable-uiscene-migration
# 项目提示重启开发工具加载项目，命令行如下提示
To ensure your app continues to launch on upcoming iOS versions, UIScene lifecycle support will soon be required. Please see https://flutter.dev/to/uiscene-migration for the migration guide.

查看iOS工程确实没有任何变化，只能参考升级文档进行手动迁移升级了。

4.2 手动迁移

对2.17.0开发的项目进行手动升级适配，根据自己项目手动升级的内容如下：

4.2.1 迁移 AppDelegate

// 原来的代码
import UIKit
import Flutter

@main
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}


// 修改后的
import UIKit
import Flutter

@main
@objc class AppDelegate: FlutterAppDelegate, FlutterImplicitEngineDelegate {
    override func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
    ) -> Bool {
        return super.application(application, didFinishLaunchingWithOptions: launchOptions)
    }
    
    func didInitializeImplicitFlutterEngine(_ engineBridge: FlutterImplicitEngineBridge) {
        GeneratedPluginRegistrant.register(with: engineBridge.pluginRegistry)
        
        
        // 原生插件的迁移从didFinishLaunchingWithOptions 迁移到这里，如果没有原生插件则忽略这一步
        let batteryChannel = FlutterMethodChannel(
            name: "samples.flutter.dev/battery",
            binaryMessenger: engineBridge.applicationRegistrar.messenger()
        )
        
        // Create platform views with `engineBridge.applicationRegistrar.messenger()`
        let factory = FLNativeViewFactory(messenger: engineBridge.applicationRegistrar.messenger())
    }
}

4.2.2 UIScene启动入口配置

info.plist中修改如下，上面AI生成的内容是不正确的，启动会是黑屏。

<key>UIApplicationSceneManifest</key>
	<dict>
		<key>UIApplicationSupportsMultipleScenes</key>
		<false/>
		<key>UISceneConfigurations</key>
		<dict>
		<key>UIWindowSceneSessionRoleApplication</key>
			<array>
			<dict>
				<key>UISceneClassName</key>
				<string>UIWindowScene</string>
				<key>UISceneDelegateClassName</key>
				<string>FlutterSceneDelegate</string>
				<key>UISceneConfigurationName</key>
				<string>flutter</string>
				<key>UISceneStoryboardFile</key>
				<string>Main</string>
			</dict>
			</array>
		</dict>
	</dict>

这一步完成之后如果项目中原生代码没有在其他生命周期函数中有其他处理，项目就能正常显示了，迁移工作也就完成了。

4.2.3 其他生命周期函数的迁移

项目中如果在iOS应用UIApplicationDelegate其他生命周期中使用了还需要进行迁移SceneDelegate对应的方法。比如applicationDidBecomeActive函数等。

在原生项目中创建SceneDelegate.swift,将AppDelegate中对应的逻辑迁移到这边即可。

import Flutter
import UIKit

class SceneDelegate: FlutterSceneDelegate {
  override func sceneDidBecomeActive(_ scene: UIScene) {
        super.sceneDidBecomeActive(scene)
        print("sceneDidBecomeActive")
    }

    override func sceneWillResignActive(_ scene: UIScene) {
        super.sceneWillResignActive(scene)
        print("sceneWillResignActive")
    }

    override func sceneWillEnterForeground(_ scene: UIScene) {
        super.sceneWillEnterForeground(scene)
        print("sceneWillEnterForeground")
    }

    override func sceneDidEnterBackground(_ scene: UIScene) {
        super.sceneDidEnterBackground(scene)
        print("sceneDidEnterBackground")
    }
}

修改Info.plist中UISceneDelegateClassName配置修改为如下

<key>UISceneDelegateClassName</key>
<string>$(PRODUCT_MODULE_NAME).SceneDelegate</string>  // FlutterSceneDelegate 

对于其他方面的迁移升级详细可参考官方升级指南

五、Android方面的升级处理

前面已经对Dart层代码进行了适配修改，配置文件也由AI初步处理了，下面就直接运行Android项目遇到问题再进行解决。

升级遇到的问题汇总：

1、构建报错tooling does not exist.

新版本的Flutter SDK中已经没有tooling这个目录了，查看新版本SDK生成的项目配置来做出修改如下

# 错误信息
Error resolving plugin [id: 'dev.flutter.flutter-plugin-loader']
> Included build '/Users/edy/flutter/packages/flutter_tools/gradle/tooling' does not exist.

# android/settings.gradle修改如下：
//    includeBuild("$flutterSdkPath/packages/flutter_tools/gradle/tooling")
includeBuild("$flutterSdkPath/packages/flutter_tools/gradle")

2、警告信息

利用AI针对警告信息调整依赖的版本即可

Warning: Flutter support for your project's Gradle version (8.5.0) will soon be dropped. Please upgrade your Gradle version to a version of at least 8.7.0 soon.
Warning: Flutter support for your project's Android Gradle Plugin version (Android Gradle Plugin version 8.3.0) will soon be dropped. Please upgrade your Android Gradle Plugin version to a version of at least Android Gradle Plugin version 8.6.0 soon.

Warning: Flutter support for your project's Kotlin version (1.8.22) will soon be dropped. Please upgrade your Kotlin version to a version of at least 2.1.0 soon.
Alternatively, use the flag "--android-skip-build-dependency-validation" to bypass this check.

Potential fix: Your project's KGP version is typically defined in the plugins block of the `settings.gradle` file (/android/settings.gradle), by a plugin with the id of org.jetbrains.kotlin.android. 
If you don't see a plugins block, your project was likely created with an older template version, in which case it is most likely defined in the top-level build.gradle file (/android/build.gradle) by the ext.kotlin_version property.

3、Java依赖

3.4.3 开发的项目依赖Java环境，运行报错如下：

The operation couldn’t be completed. Unable to locate a Java Runtime.
Please visit http://www.java.com for information on installing Java.

我这边的解决办法是用Android Studio中自带的Java版本，在Mac上面配置环境变量

export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"

4、其他问题借助AI帮忙解决就好

六、总结

通过对两个老旧项目升级到3.38.5版本SDK的过程来看，对于老旧项目的升级主要是考虑以下几点：

1、开发环境的升级

2、Dart层语法的适配升级，依赖三方库的版本升级，三方库好取决于它的迭代版本，已停止维护的库考虑替换和自己维护

3、iOS层的迁移升级，以满足最新的审核要求

4、Android 方面主要是构建工具版本的升级Gradle版本、Kotlin版本、编译版本等

5、阅读Flutter官方版本更新文档，了解那些破坏性升级点，提前了解需要升级的方面