ผู้ช่วยอัปเกรดจะเปลี่ยนไฟล์บิลด์ของโปรเจ็กต์และพยายามซิงค์บิลด์ของโปรเจ็กต์ใหม่กับ Android Studio
การดำเนินการนี้อาจใช้เวลาสักครู่หากคุณมีโมดูลจำนวนมาก เนื่องจากอาจต้องดาวน์โหลดปลั๊กอินและไลบรารีเวอร์ชันใหม่
[null,null,["อัปเดตล่าสุด 2025-07-27 UTC"],[],[],null,["# Use the Android Gradle plugin Upgrade Assistant\n\nThe Android Gradle plugin (AGP) Upgrade Assistant is a tool in Android Studio\nthat helps you upgrade the version of AGP used by your project.\n\nThere are frequent releases for AGP changes related to new features for\nconfiguring your build, new APIs for use by other Gradle plugins, and\nrefinements to the integration of the project build with Android Studio.\nUpgrading the version of AGP used by your project lets you benefit from the\nlatest features.\n| **Important:** The AGP Upgrade Assistant does not yet support projects that use [Gradle Version Catalogs](https://docs.gradle.org/current/userguide/platforms.html) or `buildSrc` to define constants and variables used in build files. For better build performance, avoid storing variables in `buildSrc`, such as dependency versions.\n\nFor more information about recommended project\nstructure for the Upgrade Assistant, see [Setup](#setup) on this page.\n\nAGP Upgrade Assistant use cases\n-------------------------------\n\nThe AGP Upgrade Assistant guides you through the changes needed to upgrade\nAGP versions. The following are the most common use cases for the Upgrade\nAssistant:\n\n- **Syntax changes**: The Upgrade Assistant attempts to translate your build\n files for an older version of AGP to those needed for a newer version of AGP.\n As AGP is developed, build files are updated to support interfaces as they\n are replaced, deprecated, or unsupported over time.\n\n- **Compatibility requirements between AGP and Gradle** : The Upgrade Assistant\n is aware of the\n [compatibility requirements between AGP and Gradle](/studio/releases/gradle-plugin?buildsystem=ndk-build#updating-gradle)\n and helps ensure that you are using the version of Gradle required for your\n version of AGP.\n\n- **Compatibility requirements between AGP and third-party Gradle plugins**: The\n Upgrade Assistant is aware of the compatibility requirements between AGP and\n some third-party Gradle plugins and helps ensure that you are using the\n versions of third-party Gradle plugins that are required for your version of\n AGP.\n\nIn general, the Upgrade Assistant makes it easier to update build files\nand understand related error messages after an AGP upgrade. The Upgrade\nAssistant also explains why the proposed changes are necessary.\n\nHow to use the AGP Upgrade Assistant\n------------------------------------\n\nTo use the Upgrade Assistant, make sure your project structure accommodates the\ntool, and then run it from Android Studio, as described in\n[Run the Upgrade Assistant](#run-upgrade-assistant).\n\n### Set up your project\n\nBefore you run the Upgrade Assistant, make sure your project is properly\nformatted and backed up. To ensure the AGP Upgrade Assistant is set up\ncorrectly, read the following sections.\n\n#### Structure your project using the Gradle build files and domain-specific language\n\nTo get the best use out of the AGP Upgrade Assistant, do the following:\n\n- **Configure the build using the Gradle build files**: The Upgrade Assistant relies on static analysis of the Gradle build files. To get the most out of the Upgrade Assistant, configure your build using these build files.\n\n| **Note:** The Upgrade Assistant does not support projects that use either [Gradle Version Catalogs](https://docs.gradle.org/current/userguide/platforms.html) or `buildSrc` to define constants and variables used in the build files. In general, we don't recommended using `buildSrc` to structure your project, because it can be inefficient. Any change to `buildSrc` constants and variables, no matter how minor, triggers a full rebuild of the project.\n\n- **Use the declarative build domain-specific language**: Gradle build files are expressed in Groovy or Kotlin. However, the more declarative the expression of the project configuration, the more likely that the Upgrade Assistant successfully finds all the places that need adjustment for an upgrade.\n\nEven if a project conforms to these limitations, the Upgrade Assistant\nmight still fail to perform a clean upgrade. See\n[Troubleshoot errors](#troubleshoot-errors) for guidance on how to resolve or\nreport bugs.\n\n#### Back up your project\n\nBefore you use the Upgrade Assistant, we recommend that your project has\nno uncommitted changes, as seen by your version control system. If you're not\nusing version control, use a backup of a last known good version\nat this point.\n\nAfter the Upgrade Assistant runs and the project is successfully built and\ntested, you can commit the new version of the project to your version control\nsystem.\n\n### Run the Upgrade Assistant\n\nTo run the Upgrade Assistant, follow these steps:\n\n1. To launch the Upgrade Assistant, navigate to\n **Tools \\\u003e AGP Upgrade Assistant** or click on the notification prompt, as\n shown in figure 1.\n\n The tool window that appears displays the details of the default upgrade\n including the project's current version of AGP and the latest version\n supported by this version of Android Studio.\n **Figure 1.** The AGP Upgrade Assistant tool window when launched with the notification prompt.\n\n \u003cbr /\u003e\n\n2. Check the required and recommended steps.\n\n In the left-hand panel, the tree with checkboxes details individual steps in\n the upgrade, categorized by whether they are required or recommended to update\n and whether they are prerequisites of other steps. Select individual\n items in the tree to display more details about each step in the main panel.\n3. To run the upgrade, select the required and desired steps and click\n **Run selected steps**.\n\n The Upgrade Assistant changes the project build files and attempts to sync the\n new project build with Android Studio. This may take a while if you have\n numerous modules, as new versions of plugins and libraries may need to be\n downloaded.\n4. Review the post-upgrade report. This report describes the steps that were\n completed and if the upgrade was successful or unsuccessful. It also includes\n an action to revert changes that were made by the upgrade assistant if there\n are issues building or testing the project after the upgrade.\n\n5. Once the project has successfully synced with Android Studio, build the\n project and run test suites to verify that the upgrade operation has not\n changed any functionality.\n\n6. Once you have verified that your project is in a good state, commit the new\n version of your project to your version control system.\n\nTroubleshoot errors\n-------------------\n\nIf the Upgrade Assistant suggests an upgrade but the upgrade fails, this is\ntypically the result of making changes to the build files, resulting in a sync\nfailure. Follow these steps to help isolate and fix the error:\n\n- First, inspect the error that led to the sync failure. Sometimes, the\n error has a clear cause, which you can address in the project's build\n files.\n\n- If the error message is not clear, or it's not obvious what is causing the\n problem, then return the project to its original state to break\n the upgrade down into smaller steps. Restore the original state from version\n control, or from backups, and make sure the project is in its original state and\n synced with Android Studio.\n\nInvestigate the error by following two kinds of upgrade breakdowns:\n\n- **Upgrade to a different version of AGP that is not the latest version.**\n If the upgrade that went wrong was an upgrade of a large number of versions,\n the best way to isolate the problem is to do a series of smaller\n upgrades, from version to version, to find the first upgrade that triggers\n the problem.\n\n- **Within an upgrade, do individual steps one at a time.** Once you determine\n the upgrade that triggers the problem, it might be possible to turn\n individual steps in the upgrade off. If it's possible, try\n doing each step one at a time to find which of those steps is responsible\n for the error. If you can't find the step responsible, check the release\n notes of any other Gradle plugins you are using for compatibility issues\n with Gradle or AGP. Sometimes, a new release addresses the use of deprecated\n or internal APIs.\n\n- **[Report a bug](/studio/report-bugs).** Sometimes all the preparatory steps\n and sync succeed but the final upgrade step still fails. In this case,\n please report a bug.\n Even if you succeed in fixing the error yourself,\n [report the original failure](/studio/report-bugs) to the bug tracker, so\n that the problem can be addressed by the development team."]]
