升級依附元件版本

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

考量升級策略

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

建構程式庫

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

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

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

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

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

建議您為程式庫建立候選版本 (RC),讓使用者提早進行測試。

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

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

如果程式庫升級需要進行重大變更,而這可能會對使用者造成特別嚴重的影響,建議您將這些變更做為新成果發布,讓舊版和新版可以並存,並且讓新版更漸進式地推出。

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

發行週期

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

縮短開發和發布週期

  • 升級時間縮短。
  • 很快就會落後。
  • 頻繁進行小幅升級有助於減輕工作負載。
  • 如果程式庫升級作業發生問題,您可以更快速地回復升級。
  • DependabotRenovate 等工具可減輕工作負載,但請務必分析結果,確認是否有風險。

開發和發布週期較長

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

隨時掌握最新功能

您是否偏好使用最新的功能和 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 相關問題。

可用的工具

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

特定升級類型的策略

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

建構依附元件及其關係
圖 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 編譯器外掛程式。Kotlin 編譯器外掛程式 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 編輯器中看到可用的升級項目,或是在使用某些依附元件工具和外掛程式時看到。

有些程式庫會指定使用該程式庫所需的最低 compileSdkminSdk。如果您未使用至少一個指定的 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 和更新的 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 變更變更程式碼?
  • 新增權限檢查嗎?
  • 建立其他測試或修改現有測試,以便因應行為變更?

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

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

成功升級的關鍵在於升級分析:

  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) 以便儲存。

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

升級並與基準比較

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

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

執行 ./gradlew dependencyGuard 來更新基準報表。然後執行版本控制系統差異比較,查看非程式庫的變更。這可能會包含比您預期還要多的程式庫升級。

分析風險

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

請考量以下事項:

主要版本升級

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

語意化版本編號中,第一個數字稱為主要版本。舉例來說,如果程式庫的版本從 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。如果您需要使用這些 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 轉換為替代方案,或是記下淘汰資訊,以便留意這些函式,並注意日後是否會移除。

使用 Lint 偵測 API 問題

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

Lint 會在 Android Studio 編輯器中執行,並在您進行變更時回報問題。但除非您使用 buildlint 目標,否則系統通常不會在 Studio 的建構作業中或執行指令列建構作業時執行此目標。

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

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

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

降低風險

確定升級風險後,請決定如何降低風險:

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

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

驗證執照

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

授權條款可能會隨著任何版本而變更。每次升級時,請確認您使用的依附元件是否已取得與應用程式或程式庫相容的授權。

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

  • 請與圖書館擁有者聯絡,要求繼續使用現有授權或雙重授權,以便繼續使用舊版授權。
  • 請與您的法律團隊合作,判斷是否可以變更您的授權,以便與服務相容。
  • 找出另一個具有相容授權的程式庫,並視需要修改應用程式。
  • 分支程式庫的最新相容版本 (如果該授權允許衍生版本,且變更不會追溯至過去),並自行進行變更。