Android Gradle 外掛程式 (AGP) 升級助理是 Android Studio 中的一項工具，可協助您升級專案使用的 AGP 版本。
經常發布與設定構建的新功能、其他 Gradle 外掛程式使用的新 API 以及專案構建與 Android Studio 整合的修正相關的 AGP 變更。升級專案使用的 AGP 版本，方便您享有最新功能。
如要進一步瞭解升級小幫手適用的建議專案結構，請參閱本頁的設定相關說明。
AGP 升級小幫手的用途
AGP 升級助理能引導您完成升級 AGP 版本所需的變更。下列為升級助理最常見的用途：
語法變更：升級助理會嘗試將舊版 AGP 的建構檔案轉換成較新版本 AGP 所需的檔案。隨著 AGP 開發，版本經過取代、淘汰或不支援，建構檔案會隨支援介面更新。
AGP 和 Gradle 之間的相容性要求：升級助理瞭解 AGP 和 Gradle 之間的相容性要求，協助確保您使用 AGP 版本所需的 Gradle 版本。
AGP 與第三方 Gradle 外掛程式之間的相容性要求：升級助理瞭解 AGP 和某些第三方 Gradle 外掛程式之間的相容性要求，協助確保您使用 AGP 版本所需的第三方 Gradle 外掛程式版本。
一般來說，升級助理可讓您在 AGP 升級後更輕鬆地更新建構檔案及瞭解相關錯誤訊息。升級助理也會說明需要提案變更的原因。
如何使用 AGP 升級助理
如要使用升級助理，請確認您的專案結構符合該工具的需求，然後從 Android Studio 執行，如執行升級升級助理中所述。
設定專案
執行升級助理之前，請確認您的專案格式正確且已備份。為確保 AGP 升級助理的設定正確無誤，請參閱下列各節。
使用 Gradle 建構檔案和網域專屬語言建構您的專案
如要充分運用 AGP 升級助理，請按照下列步驟操作：
- 使用 Gradle 建構檔案設定建構作業：升級助理使用 Gradle 建構檔案的靜態分析。如要充分運用升級助理，請使用這些建構檔案設定您的建構。
- 使用宣告式建構網域專屬語言：Gradle 建構檔案以 Groovy 或 Kotlin 表示。然而，專案設定運算式的宣告式越多，升級助理就越有可能找到所有需要調整的地方進行升級。
即使專案符合這些限制，升級助理仍可能無法執行簡潔升級作業。如要瞭解如何解決或報告錯誤，請參閱排解錯誤。
備份您的專案
使用升級助理前，建議專案沒有版本管控系統查看到的未提交變更。如果您並未使用版本管控，請在此時使用最新的已知良好版本備份。
升級助理執行後，專案順利完成建構與測試，您可將新版專案提交到版本管控系統。
執行升級助理
如要執行升級助理，請按照下列步驟操作：
如要啟動升級小幫手，請依序前往「Tools」>「AGP Upgrade Assistant」，或按一下通知提示，如圖 1 所示。
出現的工具視窗顯示預設升級的詳細資料，包括專案目前的 AGP 版本以及 Android Studio 此版本支援的最新版本。
圖 1.啟動後的「AGP Upgrade Assistant」工具視窗，內含通知提示。 查看必要和建議步驟。
左側面板中，含有核取方塊的樹狀結構會詳細說明升級的個別步驟、分類是按照其是否需要或建議更新以及其是否是其他步驟的先決條件。在樹狀圖中選取個別項目，即可在主面板中顯示每個步驟的詳細資料。
如要執行升級作業，請選取必要和所需步驟，然後按一下「Run selected steps」。
升級助理會變更專案建構檔案，並嘗試將新專案版本與 Android Studio 同步。如果有多個模組，這可能需要一段時間，因為系統可能需要下載新版外掛程式和資料庫。
查看升級後報表。這份報表會說明已完成的步驟，以及升級是否順利完成。如果升級後在建構或測試專案時遇到問題，這份報表也提供用來還原升級小幫手所做變更的操作。
專案與 Android Studio 順利同步後，建構專案並執行測試套件，確認升級作業未變更任何功能。
確認專案狀態良好後，請將專案的新版本提交至版本管控系統。
排解錯誤
如果升級助理建議升級，但升級失敗，這通常是變更建構檔案的結果，從而導致同步處理失敗。請按照下列步驟找出並修正錯誤：
首先，檢查導致同步處理失敗的錯誤。有時錯誤會有明確的原因，而您可以在專案的建構檔案中解決。
如果錯誤訊息不明確或不清楚問題所在，請將專案恢復為原始狀態，將升級分成更細的步驟。透過版本管控或備份還原至原始狀態，並確認專案處於原始狀態，並與 Android Studio 同步。
根據下列兩種升級細目來調查錯誤：
升級至不是最新版本的不同版本 AGP。如果升級發生錯誤是因大量版本的升級，取得解決問題的最佳方法就是進行一系列較小的升級，各個版本逐一進行，以找到觸發問題的第一個升級。
在升級過程中，逐一執行升級步驟。判斷出觸發問題的升級作業後，即可關閉升級中的各個步驟。如果可以的話，請嘗試逐一完成每個步驟，找出產生錯誤的步驟。如果找不到產生錯誤的步驟，請查看您使用的任何其他 Gradle 外掛程式的版本資訊，瞭解是否有 Gradle 或 AGP 的相容性問題。新版本有時會解決已淘汰或內部 API 的使用問題。
回報錯誤。有時，每個預備步驟和同步處理都成功，最終升級步驟仍會失敗。在此情況下，請報告錯誤。即使您已自行修正錯誤，請向錯誤追蹤器回報原始失敗，以便開發團隊解決相關問題。