Flutter 舊專案升級新版本：踩坑、解法與 Google Play 上架心得

萌芽站長

在 2023 之後，Flutter 官方大幅更新了專案結構與 Android 原生整合模式，許多舊專案（尤其是 2022 前建立的）在升級 Flutter SDK 與相關 plugin、打包、上架 Google Play 時，會遇到大量 breaking change。本篇整理我的真實升級流程與各種常見問題解法，給所有還在用舊專案的 Flutter 開發者參考。

1. 舊專案遇到的第一道牆：依賴與 Gradle 版本

剛開始升級 Flutter 與 Dart SDK，執行 flutter pub get、flutter pub upgrade，會發現：

多數套件（如 flutter_inappwebview、share、url_launcher）出現不相容的新版，部分已經被棄用（如 share → share_plus）。
Flutter build 失敗，出現 Gradle 版本與 Java/Dart 不相容 的錯誤。

解法：

跟著錯誤訊息升級 Gradle，gradle-wrapper.properties 改為 8.x 版（如 distributionUrl=https\://services.gradle.org/distributions/gradle-8.2.1-all.zip）。
執行 flutter pub upgrade --major-versions 升級所有依賴，再修正不相容 API（例如 Share.share 換 import 路徑）。
share 已棄用，需移除，改用 share_plus。

2. Flutter 升級後重大 breaking change — plugins block 與 settings.gradle

升級 Flutter 3.17+ 之後，build.gradle 不再允許 apply from: ... 來引入 Flutter 原生腳本，而必須用 plugins {} block。

常見錯誤與解法：

錯誤：You are applying Flutter's app_plugin_loader Gradle plugin imperatively using the apply script method...

解法：

刪除所有 apply from: ...，改用：

    plugins {
        id 'com.android.application'
        id 'kotlin-android'
    }

settings.gradle 也要移除所有 apply from: ...，否則 build 仍會失敗。

3. Kotlin DSL 支援與升級

新版 Flutter 專案預設採用 Kotlin DSL（.kts）。如果你看到 build.gradle.kts 而非傳統 build.gradle，記得：

需要手動 import Java 類別，例如：

  import java.util.Properties
  import java.io.FileInputStream

讀取簽章設定的語法也略有不同，要根據 DSL 修正。

4. 全面遷移專案架構（Flutter 官方建議）

如果你已經遇到「Your app is using an unsupported Gradle project」等無法 patch 的錯誤，
建議直接用 flutter create 新建專案，然後只搬 Dart 程式、資源與 pubspec.yaml 到新專案，
android/、ios/ 這些原生結構都用新版 Flutter 自動產生的。

這是官方推薦流程，可以徹底避免隱藏的 Gradle 相容性 bug。

5. NDK、minSdk、targetSdk 等設定檢查

部分 plugin 需要最新 NDK，需在 android { ndkVersion = "..." } 明確指定。
minSdk 建議設 21 以上，targetSdk 建議設 34 或更高。
若遇到 shrinkResources 錯誤，只要把所有 shrinkResources 設定拿掉，或加上 isShrinkResources = false。

6. API 升級踩坑與修正

Flutter 官方不斷汰舊 API，例如：
- ElevatedButton.styleFrom(primary: ...) 已棄用，請改用 backgroundColor: ...。
- flutter_inappwebview plugin 的 URLRequest(url: ...) 參數型別改為 WebUri。
記得根據新版 API 修正所有 Dart 程式碼。

7. Keystore 與 Play Console 上傳金鑰驗證

上架 Google Play 時，必須用當初上架所用的 upload-keystore.jks，
密碼、keyAlias、keyPassword 都必須正確，
不然會收到「Keystore was tampered with, or password was incorrect」或「金鑰指紋不符」的錯誤。
如果完全忘記密碼或遺失金鑰，可透過 Play Console「要求重設上傳金鑰」。

8. Play Console 新要求與打包上架細節

Google Play 2024 年起只接受 AAB（App Bundle），不可再用 APK 上架。

打包命令：

  flutter build appbundle --release

上架要準備：icon、螢幕截圖、隱私權政策、兒少性虐待及剝削（CSAE）防範政策網址。
若 app 無社群功能，CSAE 網址只要簡單聲明「不允許任何 CSAE 行為，發現會立刻刪除、配合法規」即可。

9. Debug 過程常見錯誤

java.lang.ClassNotFoundException: Didn't find class "xxx.MainActivity"
通常是搬家時 MainActivity 檔案遺漏、包名/路徑不符，建議用 flutter create . 自動補齊缺少的原生檔案。
打包 release AAB 時遇到各種資源縮減錯誤，記得檢查 buildTypes 的設定，不要設 shrinkResources。

10. 心得建議

升級 Flutter 舊專案是工程師修煉的大考！ 一步步依錯誤訊息修正，學到的東西遠比從頭新建專案還多。
強烈建議全程用 git 版本控管，每個重大調整都 commit 一次，出錯可以回頭，省下大量 debug 時間。
金鑰、密碼、政策文件等都要妥善備份，以免日後更新 app 時遇到大麻煩。
官方 breaking change 文件、pub.dev 各大 plugin 文件要多參考，少走彎路。

結語

從專案升級、API 修正、原生設定遷移、打包到成功上架，每一個細節都藏著無數陷阱，但只要冷靜排查、參考官方說明，並多和社群討論，很快就能順利完成升級！

萌芽站長

TEST