关于 agp-9-upgrade
为 Android 项目提供迁移至 AGP 9 的操作指导，面向维护 Gradle 构建的开发者。内容涵盖兼容性检查、依赖与 DSL 调整及迁移验证，并明确不适用于 KMP 项目。
主要功能
- 01检查 AGP 版本和工具兼容性
- 02迁移内置 Kotlin 与新 DSL
- 03调整 KSP、kapt 和 BuildConfig
- 04清理 gradle.properties 配置
- 05通过 Gradle 同步和构建验证
适用场景
- 01将 Android 项目升级到 AGP 9
- 02排查迁移后的 Gradle 构建问题
安装
复制下面的命令，在终端中运行。
npx skills add https:/安装后在 Claude Code 中输入/agp-9-upgrade确认已加载。
包含的文件
除 SKILL.md 外，安装时一起下载的参考资料和脚本。
references/buildconfig.mdksp-kapt.mdpaparazzi-gradle-9.mdrecipes.md详细介绍
迁移指南
请参阅 AGP 9 迁移指南，了解 AGP 9 相较于 AGP 8 的重大变更，其中许多变更具有破坏性。
要求
如果用户要求更新到 AGP 9 或迁移到 AGP 9，请先检查项目使用的 AGP 版本。如果低于 9，请停止操作，并要求用户在 Android Studio 中运行 AGP Upgrade Assistant，将 AGP 更新到最新稳定版本，并在完成后确认。用户也可能要求跳过此要求；若是如此，请在迁移到 AGP 9 的过程中将 AGP 更新到最新稳定版本。请参阅 AGP 9 迁移指南，了解如何操作。
每个 AGP 版本都与其他工具（例如 Gradle、JDK 和 Kotlin）有各自的兼容性要求。每个版本的发行说明中都会包含一个 兼容性表格，列出这些工具所需的最低版本。
KMP 项目不受支持，请勿将此技能用于 KMP 项目。
步骤
如果 AGP 已经是 9 或更高版本，请执行以下操作：
步骤 1：更新依赖项
如果项目使用了 KSP（com.google.devtools.ksp），请确保其版本为 2.3.6 或更高。
如果项目使用了 Hilt，请确保其版本为 2.59.2 或更高。
步骤 2：迁移到内置 Kotlin
请参阅指南了解详细信息。
步骤 3：迁移到新的 AGP DSL
请参阅指南了解详细信息。
另请参阅 gradle-recipes，了解如何将旧代码迁移为兼容 AGP 9 和新 DSL 的代码。
步骤 4：将 kapt 迁移到 KSP 或 legacy-kapt
如果项目使用了 KSP（com.google.devtools.ksp）或 kapt（org.jetbrains.kotlin.kapt），请参阅 KSP、kapt 和 legacy-kapt了解详细的迁移步骤。
步骤 5：BuildConfig
如果任何 Android 模块包含自定义 BuildConfig 字段，请参阅 BuildConfig了解详细信息。
步骤 6：更新 gradle.properties
迁移后，请检查 gradle.properties。移除以下标志：
- android.builtInKotlin
- android.newDsl
- android.uniquePackageNames
- android.enableAppCompileTimeRClass
此外，请删除创建的所有临时文件。
指南
- 切勿编写或运行 Python 脚本。
- 检查外部依赖项时，仅在万不得已的情况下搜索 Gradle 依赖项缓存。
- 切勿在
gradle.properties中添加android.disallowKotlinSourceSets=false。 - 验证更改时，不要运行
clean任务。这会浪费时间。
验证
迁移后，请验证以下事项：
- Gradle IDE 同步成功。
./gradlew help执行成功。./gradlew build --dry-run执行成功。
故障排除
Paparazzi v2.0.0-alpha04 及更低版本与 AGP 9 存在兼容性问题。详情请参阅 references/paparazzi-gradle-9.md。