升級依附元件版本

升級依附元件後，您就能使用最新功能、錯誤修正和改善項目。如要升級依附元件，您必須瞭解 Gradle 如何解析您要求的版本、相關風險，以及可採取的步驟來降低這些風險。

考量升級策略

風險分析是任何升級作業最重要的步驟。決定您對每個要升級的依附元件有多熟悉。制定升級策略時，有許多考量，包括：

建構程式庫

您是否要建構使用者可下載並在裝置上執行的應用程式？或者，您是否正在建構程式庫，協助其他開發人員建構應用程式？

如果您正在建構應用程式，請專注於讓應用程式保持最新且穩定。

如果您要建構程式庫，重點應放在其他開發人員的應用程式上。升級會影響使用者。如果您升級其中一個依附元件，該版本就會成為 Gradle 依附元件解析的候選版本，可能會導致應用程式無法使用該依附元件。

首先，盡可能減少程式庫的依附元件。相依性越少，對消費者的相依性解析影響就越小。

請務必遵循語意版本控制，以便指出您所進行的變更類型。舉例來說，AndroidX 遵循語義版本管理，並新增預先發布版本版本管理方案。請盡量避免升級 major 版本，以免影響使用者。

考慮為程式庫建立候選 (RC) 版本，讓使用者及早進行測試。

如要進一步瞭解如何讓程式庫的應用程式二進位檔介面 (ABI) 保持相容性，請參閱「程式庫作者的回溯相容性指南」。使用整合測試和二進位檔相容性驗證工具等工具，確保 ABI 變更符合預期的版本變更。

如果您將 patch 中的修正程式發布至較舊的程式庫版本，使用者就不需要將程式庫升級至下一個 major 或 minor 版本，除非他們想要使用新功能。請避免升級這些升級中的遞移依附元件。

如果消費者覺得程式庫升級需要特別令人困擾的破壞性變更，不妨以新構件發布版本，這樣既能同時發布新舊版本，也能逐步推出。

注意：如果依附元件的升級作業包含重大的 API 變更，建議您在 major 或 minor 版本中進行升級，並進行必要的變更。如果您沒有這麼做，程式庫使用者可能會這麼做，導致程式庫與該依附元件之間不相容。即使媒體庫沒有異動，仍有可能發生這種情況。您可以發布新版本，專門用來升級該依附元件。

發行週期

您多常發布應用程式或程式庫？

縮短開發和發布週期

  • 節省升級時間。
  • 您很快就能落敗。
  • 頻繁進行小幅升級可以減輕工作負載。
  • 如果程式庫升級作業發生問題，您可以更快速地回復升級。
  • Dependabot 和 Renovate 等工具可以減少工作負載，但請務必分析結果，檢查是否有風險。

開發和發布週期較長

  • 您有更多時間進行升級作業並進行測試。
  • 依附元件的較新版本較有可能在您的週期中發布。
  • 復原升級和發布應用程式或程式庫所需的時間較長。

隨時掌握最新功能

您偏好使用最新的功能和 API，還是只在需要功能或錯誤修正時才升級？

請考量經常升級的優缺點。日後的升級作業較為簡單 (要整合的變更數量較少)，但帶來升級風險的頻率更高。

測試升級至預先發布版 (Alpha 版、Beta 版、候選版) 程式庫版本，有助於在穩定版發布時做好準備。

新的依附元件

如果您要新增新的依附元件，建議您採用嚴格的審查程序，檢查該程式庫是否符合所有風險標準，確保已妥善評估。不允許在未經審查的情況下新增依附元件。

專責團隊

您是否有專屬的建構團隊？您的軟體工程師是否會維護建構項目？專責團隊通常可以花更多時間分析升級風險，並測試新版本，確保工程師在使用新版本前，建構作業能正常運作。

升級類型

有些升級作業比其他作業更重要。請想想哪個項目對您來說最重要。

建構工具升級作業 (例如 Gradle 和 Gradle 外掛程式) 通常對使用者造成的影響較小，且大部分風險都與建構作業有關。建構作業本身有助於驗證這些變更。程式庫和 SDK 升級作業較難驗證，對使用者而言風險也較高。

Android Gradle 外掛程式 (AGP)：用於建構 Android 應用程式或程式庫的工具。這是您可以進行的最重大升級，因為這類升級通常包含或啟用效能改善項目、錯誤修正、新的 Lint 規則，以及支援新的 Android 平台版本。

Gradle：升級 AGP 或其他 Gradle 外掛程式時，通常需要升級 Gradle。

其他 Gradle 外掛程式：Gradle 的 API 有時會變更。升級 Gradle 時，請檢查所用外掛程式的升級版本。

Kotlin 和 Java：某些程式庫和外掛程式需要 Kotlin 或 Java 的最低版本，或是您想利用新的語言功能、API 或效能改善功能。

Android 平台：Play 商店需要定期升級 Android SDK。您應盡快測試新版 Android SDK。有些 SDK 升級作業需要變更您的應用程式，例如加入新的權限或使用新的 API。

程式庫：您是否想根據程式庫與整體架構的關聯性，為其設定優先順序？

  • 平台和架構相關程式庫 (例如 AndroidX) 通常會為了利用新功能而變更，或協助抽象平台變更。每次升級 Android 平台或其他架構相關程式庫時，請至少升級這些程式庫。
  • 除非您需要新功能或特定錯誤修正，否則其他程式庫升級作業可以分散或延遲。

Android Studio：請保持 Android Studio 為最新版本，以便使用最新的 IntelliJ IDEA 平台和工具，並修復最新的 Android SDK 相關錯誤。

可用的工具

有許多工具和外掛程式可協助您升級。Dependabot 和 Renovate 等工具會自動升級建構中的程式庫版本，但請務必分析結果，確認是否有風險。

特定升級類型的策略

升級某些類型的依附元件可能會產生連鎖效應，導致需要升級其他類型的依附元件。我們會在「工具和程式庫的互相依賴關係」一文中討論建構元素之間的關係。

建構依附元件及其關係
圖 1. 建立關係。

升級各類型的元件時，請考慮升級作業對建構中其他元件的影響。

Android Gradle 外掛程式 (AGP)

Android Studio 內建 AGP 升級工具，可協助您完成這些工作。

如果您使用助理或手動進行升級，請考量以下事項：

請參閱 AGP 版本資訊。

升級 Gradle至至少所列版本。

將 Android Studio 升級至支援所選 AGP 版本的版本。

使用支援 Android SDK 的 Android Studio 和 AGP 版本。

檢查 SDK Build Tools、NDK 和 JDK 的相容性。

如果您開發的 Gradle 外掛程式 (供內部或公開使用) 會擴充或使用 AGP 的資料，請檢查是否需要升級外掛程式。有時 AGP 會淘汰 API，並在日後移除，導致與先前外掛程式不相容。

Kotlin 編譯器、語言和執行階段

請參閱 Kotlin 版本資訊，瞭解已知問題和不相容性問題。

如果您使用 Jetpack Compose：

如果您使用 Kotlin Symbol Processing (KSP)，請參閱 KSP 快速入門瞭解如何設定，並參閱 KSP 版本瞭解可用的版本。請注意，您必須使用與 Kotlin 版本相符的 KSP 版本。舉例來說，如果您使用的是 Kotlin 2.0.21，則可以使用開頭為 2.0.21 的 KSP 外掛程式任何版本，例如 2.0.21-1.0.25。您通常不需要升級 KSP 處理器 (例如 Room 編譯器，會在建構檔案中顯示為 ksp 依附元件)；KSP 外掛程式會抽象化大部分的編譯器 API，而處理器使用的 KSP API 則是穩定的。

升級您使用的所有其他 Kotlin Compiler 外掛程式。Kotlin Compiler Plugin API 通常會在不同版本之間變更，而且外掛程式必須使用相容的 API。如果外掛程式列於「Compiler plugins」中，則必須使用與 Kotlin 編譯器相同的版本。如要瞭解其他編譯外掛程式，請參閱相關說明文件，瞭解適當的對應方式。

請注意，如果編譯器外掛程式未與 Kotlin 編譯器本身一併維護，則通常會因為等待編譯器外掛程式 API 穩定而延遲發布。升級 Kotlin 前，請確認您使用的所有編譯器外掛程式是否有相應的升級版本。

最後，在某些情況下，Kotlin 語言會變更，您必須更新程式碼。這通常是因為你在試用實驗功能，如果升級 Kotlin 編譯器後程式碼無法正確建構，請參閱 Kotlin 發布說明，確認是否有語言變更或執行階段程式庫損壞的情況。

Kotlin 編譯器外掛程式

如要升級 Kotlin 編譯器外掛程式，請升級至相符的 Kotlin 版本。

大多數 Kotlin 編譯器外掛程式都會使用與 Kotlin 編譯器相同的版本，或是從 Kotlin 編譯器的必要版本開始。舉例來說，如果外掛程式版本為 2.0.21-1.0.25，您就必須使用 Kotlin 編譯器的 2.0.21 版。

變更 Kotlin 編譯器版本時，有時需要其他變更。

程式庫

程式庫是建構作業中最常升級的依附元件。Android Studio 編輯器中，或者如果您使用某些依附元件工具和外掛程式，就會看到可用的升級項目。

有些程式庫會指定使用該程式庫所需的最低 compileSdk 或 minSdk。如果您未使用至少一個指定的 compileSdk，建構作業就會失敗。不過，應用程式的 minSdk 會自動設為程式庫依附元件和建構檔案中所有 minSdk 值的最大值。

有些程式庫也會指定可使用的最低 Kotlin 版本。請更新建構檔案中的 Kotlin 版本，至少為指定的版本。

Gradle

有時新版 Gradle 會淘汰現有的 API，並在日後的版本中移除這些 API。如果您開發 Gradle 外掛程式，請盡快升級外掛程式，尤其是公開的部分。

部分 Gradle 升級作業需要找出您使用的新版外掛程式。請注意，依據最新的 Gradle 外掛程式 API 升級外掛程式時，這些外掛程式可能會在開發過程中延遲。

如要升級 Gradle，請按照下列步驟操作：

  • 請參閱版本資訊，瞭解要使用的版本。
  • 升級 gradle/wrapper/gradle-wrapper.properties 中的 Gradle 版本。
  • 執行 ./gradlew wrapper --gradle-version latest，升級 Gradle 包裝函式 jar 和指令碼。
  • 升級 Gradle 外掛程式。
  • 升級用於執行 Gradle 的 JDK。

Gradle 外掛程式

升級後的 Gradle 外掛程式有時會使用新的或已變更的 Gradle API，這會導致 Gradle 升級或建構檔案中的設定變更。無論是哪種情況，您都會看到表示不相容的建構警告或錯誤。

每次升級外掛程式時，請升級 Gradle。

Android SDK

Android Studio 內建 Android SDK 升級工具，可協助您完成這些工作。

如果您使用助理或手動進行升級，請考量以下事項：

每個 Android SDK 版本都包含新功能和 API、錯誤修正和行為變更。Play 商店要求更新您的 targetSdk，但建議您在期限前更新 targetSdk，有充裕的時間進行必要變更。

升級 Android SDK 前，請詳閱版本資訊。密切留意行為變更部分，包括：

  • 在安裝或執行階段要求的新權限。
  • 已淘汰的 API 及其替代項目。
  • 對 API 或行為做出破壞性變更。
  • 新的 Kotlin 或 Java API，可能會影響程式碼。

行為變更部分可能會相當冗長，但請仔細閱讀，因為這裡通常會列出您需要對應用程式進行的重要變更。

您必須升級 targetSdk，才能符合 Play 商店規定。您可以選擇升級 compileSdk，以便存取新的 API。請注意，部分程式庫 (例如 AndroidX) 至少包含 compileSdk 基本需求。

如要在開發期間充分利用新的 SDK 功能，並確保建構期間的相容性，請升級 Android Gradle 外掛程式 (AGP) 和 Android Studio。包括新 SDK 的全新及改良工具。請參閱「支援 Android API 級別的最低工具版本」。

升級 Android SDK 時，請升級您使用的所有 AndroidX 程式庫。AndroidX 通常會使用全新和更新後的 API，提升各 Android SDK 版本的相容性和效能。

Android Studio

您通常可以隨時升級 Android Studio。您可能會看到提示您升級 AGP 或升級 Android SDK 的訊息。我們強烈建議您升級，但這並非必要步驟。

如果日後想使用 Android Studio 升級 AGP 或 Android SDK，可以在「Tools」選單中找到這些選項：

Java

如果 Android 應用程式中有 Java 原始碼，建議您使用較新的 Java API。

每個 Android SDK 版本都支援部分 Java API 和語言功能。AGP 會使用名為「desugaring」的程序，提供舊版 Android SDK 的相容性。

Android SDK 版本資訊會說明支援的 Java 級別和潛在問題。由於 Kotlin 可存取相同的 Java API，因此其中部分問題也可能會影響 Kotlin 原始碼。即使您沒有 Java 原始碼，也請務必密切留意發布說明書行為變更部分中顯示的 JDK API 部分。

您可以在建構指令碼中的多個位置指定 JDK 使用。詳情請參閱「Android 建構作業中的 Java 版本」。

升級分析

升級依附元件可能會帶來風險，例如 API 和行為變更、新的使用需求、新的安全性問題，甚至是授權變更。例如，您是否需要：

  • 是否要針對 API 變更變更程式碼？
  • 要新增權限檢查嗎？
  • 是否要建立其他測試或修改現有測試，以便因應行為變更？

請注意，您升級的依附元件已升級其依附元件的版本。這可能會迅速擴散成大量變更。

如果您使用 Renovate 或 Dependabot 等工具自動執行升級，請注意，這類工具不會為您進行分析，而是升級至最新的程式庫版本。請勿假設在進行這類自動升級後，所有內容都會正常運作。

升級成功的關鍵是升級分析：

  1. 判斷與升級前後的依附元件差異。
  2. 檢查各項變更，並判斷所涉及的風險。
  3. 降低風險，或接受或拒絕變更。

判斷依附元件差異

升級分析的第一步，就是決定依附元件的變更方式。善用版本管控系統 (VCS，例如 Git) 和 Dependency Guard 外掛程式，快速查看變更。目標是建立「之前」和「之後」的快照，並進行比較。

設定並建立第一個基準

開始升級前，請確認專案已順利建構。

建議您盡可能解決警告，或是建立基準，以便追蹤您已看到哪些警告。

這些警告基準可讓您更輕鬆地在升級依附元件時看到新出現的警告。

設定及執行 Dependency Guard，建立依附元件基準。在 gradle/libs.versions.toml 版本目錄中新增：

[versions]
dependencyGuard = "0.5.0"

[plugins]
dependency-guard = { id = "com.dropbox.dependency-guard", version.ref = "dependencyGuard" }

並在應用程式的建構檔案中新增以下內容：

Kotlin

plugins {
    alias(libs.plugins.dependency.guard)
}

dependencyGuard {
    configuration("releaseRuntimeClasspath")
}

Groovy

plugins {
    alias(libs.plugins.dependency.guard)
}

dependencyGuard {
    configuration('releaseRuntimeClasspath')
}

releaseRuntimeClasspath 設定是可能的目標，但如果您想使用其他設定，請在建構檔案中不列出設定，然後執行 ./gradlew dependencyGuard，即可查看所有可用的設定。

設定完成後，請執行 ./gradlew dependencyGuard 在 app/dependencies/releaseRuntimeClasspath.txt 中產生報表。這是基準報表。將此內容提交至版本管控系統 (VCS) 以便儲存。

請注意，依附元件 Guard 只會擷取程式庫依附元件的清單。建構檔案中還有其他依附元件，例如 Android SDK 和 JDK 版本。在依附元件變更前提交至 VCS，可讓 VCS 差異顯示這些變更。

升級並與基準比較

有了基準後，請升級依附元件和其他要測試的建構變更。請勿在此時升級原始碼或資源。

執行 ./gradlew lint 即可查看新的 Lint 警告或錯誤。請解決所有重要問題，然後執行 ./gradlew lint -Dlint.baselines.continue=true 更新警告基準。如果您使用其他工具擷取警示基準線 (例如 Kotlin 警示基準線或 Kotlin 警示基準線產生器)，請一併處理新警示並更新基準線。

執行 ./gradlew dependencyGuard 來更新基準報表。接著，執行 VCS diff 即可查看非程式庫變更。包含的程式庫升級可能比您想像的多。

分析風險

瞭解變更內容後，請考量升級每個程式庫可能帶來的風險。這有助於您專注於測試或深入調查變更。定義一組專案風險，以便進行分析，確保分析結果一致。

請考量以下事項：

主要版本提高

主要版本號碼是否有變更？

在語意化版本編號中，第一個數字稱為主要版本。舉例來說，如果程式庫的版本從 1.2.3 升級至 2.0.1，則主要版本已變更。這通常表示程式庫開發人員在不同版本之間做出不相容的變更，例如移除或變更 API 的部分。

看到這項訊息時，請特別留意受影響的程式庫，並參考下列任何一項注意事項。

如果程式碼使用任何實驗性 API (通常需要使用註解或建構檔規格才能啟用)，即使是次要或修補程式版本變更 (例如從 1.2.3 升級至 1.3.1 或從 1.2.3 升級至 1.2.5)，也可能會帶來額外風險。

不穩定的 API

部分程式庫版本可能包含不穩定的 API。這些 API 通常是處於開發階段，或依附於其他不穩定的 API。

雖然通常只限於預先發布版，例如 Alpha 版、開發人員版或實驗性版本，但有些程式庫會包含標示為實驗性或不穩定的 API。

請盡量避免使用這類 API。如需使用，請務必記錄您的使用情形，並在後續版本中留意變更或移除的情形。

動態行為

部分程式庫的行為會因外部因素而有不同行為。舉例來說，與伺服器通訊的程式庫會依伺服器的變更而變動。

  • 程式庫是否需要與特定伺服器版本相符？
  • 程式庫可以連線至不同版本的伺服器嗎？
  • 是否有其他外部因素會影響程式庫的正常行為？

資訊清單合併

以 Android 封存檔 (AAR) 形式發布的程式庫，可包含合併至應用程式的資源和資訊清單。這些檔案可新增權限和 Android 元件，例如間接執行的活動或廣播接收器。

執行階段更新

部分程式庫會使用可在應用程式外部更新的功能。程式庫可能會使用 Play 服務，而 Play 服務會獨立於 Android SDK 升級。其他程式庫可能會綁定至獨立更新的外部應用程式 (通常使用 AIDL) 中的服務。

你要略過幾個版本？

等候升級程式庫的時間越長，潛在風險就越大。如果您發現版本有重大變動 (例如從 1.2.3 變更為 1.34.5)，請特別留意這個程式庫。

遷移指南

檢查程式庫是否有遷移指南。這麼做可大幅減少風險分析和風險緩解規劃。

請注意，如果開發人員提供這類指南，表示他們重視相容性，並考慮到升級緩解措施。

版本資訊

請參閱每個變更程式庫的版本資訊 (如有提供)。請留意是否有破壞性變更或新要求，例如新增權限。

README

程式庫中的某些 README 檔案列出潛在風險，尤其是在程式庫未提供版本資訊的情況下。查看「已知問題」，特別是已知的安全性疑慮。

檢查已知的安全漏洞

Play SDK 索引會追蹤許多熱門 SDK 的安全漏洞。Play 管理中心會回報您使用的 SDK 是否含有已知安全漏洞。在 Android Studio 中編輯建構檔案時，IDE 會檢查 SDK 索引，並標示使用安全漏洞資料庫的版本。

美國國家標準暨技術研究院 (NIST) 維護龐大的國家漏洞資料庫 (NVD)。Dependency Check Gradle 外掛程式會根據 NVD 檢查您使用的依附元件。

如要使用 Dependency Check，請申請 NVD API 金鑰、設定 Gradle 外掛程式，然後執行 ./gradlew dependencyCheckAnalyze。請注意，這項作業可能需要很長的時間才能執行完畢。

版本衝突

版本是否能正常解析？請找出衝突，尤其是主要版本差異。如要進一步瞭解如何查看衝突，請參閱「Gradle 依附元件解析」。尤其是在 ./gradlew app:dependencies 報表中搜尋 ->。

請盡可能與依附元件的作者合作，以釐清依附元件。如果貴公司允許，請為程式庫做出變更 (上游)，以提高程式庫的相容性。

檢查執照

升級程式庫時，請確認授權是否有異動。程式庫本身可能會變更為與應用程式或程式庫不相容的授權。新的遞移依附元件也可能產生不相容的授權。如要進一步瞭解如何檢查依附元件目前的授權組合，請參閱「驗證授權」。

維護與
品質風險

有公開存放區的程式庫：

  • 有多少貢獻者在維護程式庫？
  • 上次升級是什麼時候？程式庫變更的頻率為何？
  • 問題積壓情形 (如有) 為何？快速瀏覽，瞭解程式庫的潛在問題和技術債務。
  • 單元測試涵蓋程式庫的程度如何？
  • 程式碼庫中是否有已知的反模式？
  • 圖書館是否已妥善記錄？
  • 程式碼集中是否有許多 _fixme_ 註解？

開放原始碼與封閉原始碼

無論問題出在程式碼或程式庫程式碼，如果程式庫是開放原始碼，比起封閉原始碼，更容易進行偵錯。

盡量減少封閉來源依附元件，並在評估期間套用額外審查。是否有其他適合您用途的替代方案？封閉原始程式庫提供哪些服務水準協議？如果您選擇使用封閉原始碼依附元件，請準備編寫其他測試案例，以協助降低風險。

執行建構作業

建構您的專案。尋找新的錯誤或警告。如果您能找出導致這些問題的程式庫，請注意升級該程式庫可能會帶來風險。

如果您看到任何新的折舊警告，請將這些警告視為產生警告的程式庫的特定風險。這些項目可能會在後續版本中移除。如要繼續使用該程式庫，請花時間從使用已淘汰的 API 轉換至替代 API，或留意淘汰功能，密切留意這些函式，以及日後是否會移除。

使用 Lint 偵測 API 問題

Android Lint 可找出應用程式中的許多問題，包括一些是依附元件版本或 Android SDK 變更產生的問題。舉例來說，如果您升級 compileSdk 並使用其新的 API，Lint 就會回報先前 SDK 版本中不支援的 API。

Lint 會在 Android Studio 編輯器中執行，並在您進行變更時回報問題。不過，除非您使用 build 或 lint 目標，否則一般不會在 Studio 的建構作業中，或是在執行指令列建構作業時執行。

如果您使用持續整合 (CI)，請在 CI 建構期間 (或至少在每晚建構時) 執行 gradlew build 或 gradlew lint，以便偵測這類錯誤。

如果您不使用 CI，請務必至少偶爾執行 gradlew lint。

請特別留意 Lint 錯誤和警告。有些程式庫會附帶專屬的 Lint 檢查，協助確保 API 的正確使用方式。部分程式庫的新版本包含新的 Lint 警告和錯誤，因此在建構時會產生新的報告。

降低風險

確定升級風險後，請決定如何降低風險：

  • 接受部分風險。部分風險低到可以接受，尤其是在升級時間和資源有限的情況下。
  • 完全拒絕某些風險。部分升級作業可能風險過高，特別是在您目前的時間或資源有限，無法減輕風險的情況下。如果您需要進行分類，請著重於針對遇到的錯誤或所需的新功能進行升級。
  • 降低其餘風險
    • 請考慮將升級作業批次處理成較小的獨立變更組合。 這有助於降低整體風險並允許部分回溯。
    • 詳細調查變更。
    • 測試應用程式，檢查是否有非預期的變更。若需要在升級過程中建立信心，請新增新的測試。
    • 發現有疑問的內容時，請查看來源 (如有)。
    • 在來源或建構中進行必要變更。

記錄決策。如果升級帶來的風險在執行應用程式時變成問題，風險分析文件可以減少必要的錯誤分析。

驗證執照

程式庫開發人員會授權您使用程式庫。您必須遵守授權條款，才能使用程式庫。部分授權非常寬鬆，通常只需要註明程式庫，並向使用者顯示授權文字。有些程式庫被視為「病毒式」；如果您使用這些程式庫，就必須將相同的授權套用至應用程式或程式庫。

授權條款可能會隨著任何版本而變更。升級時，您應驗證使用的依附元件是否以與應用程式或程式庫的相容方式授權。

如果授權不相容 (或變更為不再相容)，您無法使用該版本的程式庫。包括：

  • 請與程式庫擁有者聯絡，要求延續現有授權或雙授權，以繼續允許舊授權。
  • 請與您的法律團隊合作，判斷是否可以變更您的授權，以便與 Google 服務相容。
  • 找出另一個具有相容授權的程式庫，並視需要修改應用程式。
  • 建立程式庫的最後一個相容版本 (如果此授權允許衍生，且變更不溯及既往)，並自行進行變更。