最近把公司的项目从 Gradle 8.2 直接升到了 8.13Android Studio 也跟着升级到了最新版。本来以为只是版本数字往前走了一格结果从打开项目那一刻起配置缓存、Kotlin DSL、AGP 版本矩阵这些事全挤到一块儿来了。最难受的是网上能找到的资料大多还停留在 Gradle 7.4、AGP 7.5 的旧时代要么就是把 Gradle 8.13 和 Android Studio 新版本混在一起讲看完反而更懵。这篇内容我不打算复述官方 Release Notes那些你翻开文档就能看到。我重点写实际踩到的坑、用过的排查方法以及哪些网上流传的“解决方案”纯属误导、千万别照抄。如果你正打算把项目升级到 Gradle 8.13或者已经被新版本的报错折磨到怀疑人生这份避坑指南应该能帮你省下不少时间。1. 为什么大家都在升 Gradle 8.13以及升级前必须落实的三件事1.1 Gradle 8.13 到底改了什么先说最影响你日常的四个变化Gradle 8.13 不是那种改个版本号就完事的小迭代。它对构建脚本的严谨程度、任务配置的时机、依赖解析的方式都有调整。用大白话说以前很多“糊弄着能用”的写法在新版本里直接被列为错误或者至少是警告。第一个变化是 JDK 运行要求。Gradle 8.13 在运行时对 JDK 版本的要求抬高了以前项目里用 JDK 11 跑构建在 8.13 下会遇到各种诡异问题。虽然官方还保留了一定的向下兼容能力但我在实际体验中老老实实切到 JDK 17 之后构建立刻稳定下来。如果你用的是 JDK 21那更好新版本对 JDK 21 的支持明显比老版本完善尤其是配合 Kotlin 插件的场景。第二个变化是 Kotlin DSL 的进一步收紧。从 Gradle 8.x 早期版本开始官方就在推 Kotlin DSL但到了 8.13Kotlin DSL 的编译期检查更严格了。你在 build.gradle 里写的每段 Kotlin 脚本都会被真正编译成代码这意味着很多旧写法会在配置阶段直接报错而不是像 Groovy 那样“看起来能跑就跑了”。很多团队的构建脚本从 Groovy 迁移到 Kotlin DSL 时都卡在这一步。第三个变化是配置缓存Configuration Cache进入更成熟的阶段。Gradle 8.13 对配置缓存的支持度已经相当高但它带来的限制也让很多自定义 Task 作者头疼。核心问题很简单你的构建脚本里只要有一处直接读取了project对象、调用了外部进程或者把不该序列化的东西放进了 Task开启配置缓存后就会报错。第四个变化是依赖解析的校验更严格。Gradle 8.13 对依赖冲突、动态版本、仓库认证这些字段的检查变得更细以前能忽略的问题现在会在构建日志里明确提示某些情况下甚至会直接失败。这些变化单独拎出来都不难处理但叠在一起就成了升级路上的连环坑。所以我建议你先别急着改代码先把下面三件事落实。1.2 第一件事先核对 AGP 版本矩阵顺序错了全局崩我见过太多人一上来就改gradle-wrapper.properties把 distributionUrl 换成 8.13然后执行同步结果 Android Gradle PluginAGP直接抛出一句“Minimum supported Gradle version is 8.x”。AGP 和 Gradle 之间是绑定关系不是“新版 Gradle 能兼容所有旧版 AGP”。我实测下来在 Gradle 8.13 环境下AGP 至少要到 8.6 以上才比较稳妥。如果你的项目还在用 AGP 7.4、7.5那基本是升不上去的要么先升 AGP要么先别碰 Gradle。我这里给一个我实测过的兼容组合表不是官方完整矩阵但作为参考足够Gradle 版本AGP 最低建议说明7.47.3老项目常见组合8.28.2上一代常见组合8.108.5中等幅度升级8.138.6稳定组合实测可跑升级顺序真的很重要。最安全的方式是先单独升 AGP在旧版 Gradle 上验证通过然后再升 Gradle 到 8.13最后再打开配置缓存等新特性。顺序反了报错定位起来会非常痛苦因为你根本无法区分是 AGP 不兼容还是 Gradle 新特性导致的问题。1.3 第二件事备份构建脚本与 Wrapper别把老版本丢了这个建议听起来很基础但我身边真有人升级到一半想回退结果发现连gradle-8.2-all.zip都下载不到了。Gradle 老版本安装包虽然还能找到但如果你的搭建环境网络受限下载老版本本身就是个麻烦。我建议在动任何配置文件之前先把关键文件打个包tar -czf gradle-backup.tar.gz \ settings.gradle.kts \ build.gradle.kts \ gradle.properties \ gradle/libs.versions.toml \ gradle/wrapper/gradle-wrapper.properties \ app/build.gradle.kts注意这里的app/build.gradle.kts可以根据你实际模块数量来调整多模块项目建议把每个模块的构建文件都放进备份。如果担心遗漏直接对整个项目做一次 Git 提交就是最好的备份。我还会额外记录一下升级前的环境信息方便对比./gradlew --version ./gradlew :app:tasks --all这两条命令的输出建议单独保存。升级后再跑一次对比任务列表你会很清楚地看到哪些任务被合并、哪些任务被移除。很多时候你以为“任务少了”其实只是任务被重新组织成了按需注册。1.4 第三件事JDK 和 Gradle 的版本配套Gradle 8.13 对 JDK 版本的要求我建议直接用 Android Studio 内置的 JBR 版本或者手动安装 Temurin JDK 17。你可以在gradle.properties里显式指定 JDK 路径避免 IDE 和命令行工具的 JDK 不一致org.gradle.java.home/Library/Java/JavaVirtualMachines/temurin-17.jdk/Contents/HomeWindows 下的写法类似只是路径格式不同。我踩过的一个坑是这样IDE 里设置的 JDK 是 17但系统环境变量JAVA_HOME指向了 JDK 11在终端里跑./gradlew时用的是 JDK 11结果构建报各种找不到类的错。这个问题在 Gradle 8.13 里还特别隐蔽因为很多报错信息指向的是你自己的代码而不是 JDK 本身。排查半天才发现是JAVA_HOME没对上。所以升级前先执行一次./gradlew --version确认上面显示的 Java 版本和你预期一致$ ./gradlew --version ------------------------------------------------------------ Gradle 8.13 Java version: 17.0.9另外涉及 Java Toolchain 的项目也要注意jvmToolchain(17)和 Gradle 运行时的 JDK 是两回事。前者决定编译 Java 代码时用的 JDK后者决定 Gradle 守护进程本身跑的 JDK。8.13 对这两者的校验更严格如果 Toolchain 版本高于 Gradle 运行 JDK 版本某些任务会直接跳过甚至报错。2. 构建脚本改造Kotlin DSL 与配置缓存的真实坑点2.1 Kotlin DSL 类型推断为什么会突然报错升级到 Gradle 8.13 后Kotlin DSL 脚本的报错率显著上升。最常见的表现是以前能跑的compileSdkVersion(33)突然报“Unresolved reference”。这不是魔法而是 Kotlin DSL 的扩展接口在编译时被更严格地处理了。旧版本的com.android.build.api.dsl.CommonExtension接口中compileSdkVersion方法还在新版本里接口改成属性compileSdk方法被废弃。Kotlin DSL 的编译期类型检查会明确告诉你不存在这个函数但在 Groovy 脚本里它可能默默通过了。我在实际项目中处理的典型报错长这样e: org.gradle.kotlin.dsl.execution.ProblematicCodeExecutionException: Could not get unknown property compileSdkVersion for extension android修复方式很简单把方法调用改成属性赋值android { compileSdk 34 defaultConfig { applicationId com.example.app minSdk 23 targetSdk 34 versionCode 101 versionName 1.0.1 } }同样的变化还影响buildToolsVersion、minSdkVersion、targetSdkVersion这类写法。别在脚本里继续用老方法直接改成属性赋值一次改完。Kotlin DSL 还有一个让很多人困惑的点依赖写法中的引号。Groovy 里一行implementation com.android.support:appcompat-v7:28.0.0直接写Kotlin DSL 里需要括号implementation(com.android.support:appcompat-v7:28.0.0)。如果你在混用脚本IDE 的迁移提示会帮你大部分忙但还是要自己扫一遍。2.2 配置缓存在 8.13 里更严格了别再用旧写法Gradle 配置缓存的原理简单说就是把配置阶段的输出缓存下来下次构建直接跳过配置阶段从缓存里读取状态。这样能大幅缩短冷启动时间但前提是你的配置阶段没有“副作用”。在 Gradle 8.13 里配置缓存对任务实现类的约束非常严。最典型的坑是任务里直接用到project对象比如tasks.register(printBuildDir) { doLast { println(project.layout.buildDirectory.asFile.get().toString()) } }这段代码在不开启配置缓存时完全没问题但开启之后Gradle 会警告你任务引用了不安全的Project实例缓存无法启用。原因在于配置缓存需要序列化任务输入而Project本身不是可序列化对象。解决办法是改用ProjectLayout或者直接使用layouttasks.register(printBuildDir) { doLast { println(layout.buildDirectory.asFile.get().toString()) } }还有一个常见坑是对外部进程的调用。比如某个自定义任务在doFirst里执行Runtime.exec()或使用ProcessBuilder启动外部命令。配置缓存会尝试序列化任务状态而外部进程的执行时间和结果不是可预测的Gradle 会直接拒绝缓存。如果你暂时没有精力改造任务可以先不开启配置缓存在gradle.properties里注释掉# org.gradle.configuration-cachetrue等所有任务都适配后再打开。别把配置缓存当作必选项它是性能优化不是功能依赖。我见过有人升级后强行开启配置缓存结果自定义任务在第二次构建时输出错误这比构建慢更恶心。2.3 Task 任务列表急剧变少到底是不是 bug搜热词的时候看到“android studio 的 task 任务少”这个问题我太有共鸣了。升级 Gradle 8.13 后Android Studio 的 Gradle 面板里任务数量肉眼可见地变少很多人以为升级坏了。其实不是 bug而是 Gradle 8.13 配合新版 AGP 后任务注册策略变了。很多任务是按需注册的只有在特定条件满足时才会出现在任务图中。比如bundleRelease任务只有你配置了签名信息或者满足变体要求时才会被注册。要查看完整的任务列表不要只看 IDE 面板直接在终端跑./gradlew :app:tasks --all这个命令会列出该模块下几乎所有可执行任务。如果某个任务没有出现可能是它依赖的配置没有被激活。还有一种情况是构建变体选择错误IDE 右下角的 Build Variants 如果选的不是debug或release任务列表自然不一样。我在项目里还遇到一个特例某些自定义任务被 AGP 的变体 API 过滤了。这是因为 AGP 新版本会基于变体属性来裁剪任务图如果你的自定义任务没有关联到某个具体的 Build Type 或 Product Flavor在 IDE 面板里就看不到。这不算问题正常执行./gradlew时任务还会运行。2.4 从 Groovy 迁移到 Kotlin DSL 的经验备忘Gradle 8.13 官方越来越倾向 Kotlin DSL新建项目的默认脚本都是.kts。但存量项目大量是 Groovy 脚本这时候混用问题就来了。我建议从 Groovy 迁移到 Kotlin DSL 时准备好一份对照表减少踩坑时间场景Groovy 写法Kotlin DSL 写法依赖声明implementation com.google.android.material:material:1.9.0implementation(com.google.android.material:material:1.9.0)仓库配置mavenCentral()mavenCentral()签名开关minifyEnabled falseisMinifyEnabled false变量定义def versionName 1.0val versionName 1.0manifest 占位符manifestPlaceholders [key: value]manifestPlaceholders[key] value这里最容易出错的是isMinifyEnabled。Groovy 里minifyEnabled false看起来像属性赋值但在 Kotlin DSL 里布尔属性前面必须加is前缀否则编译不过。还有一个细节是扩展函数。Kotlin DSL 允许你写一些辅助函数来简化多模块的版本管理配合 Version Catalog 使用效果更好。如果你已经在用libs.versions.toml那迁移工作量会小很多。没有用 Version Catalog 的话建议这次升级顺手引入以后版本更新会清爽很多。3. AGP 版本与 Gradle 8.13 的兼容性细节3.1 AGP 版本选择不是越高越好要匹配 GradleGradle 8.13 能兼容的 AGP 范围其实很宽但“能跑”和“跑得稳”是两回事。在我的测试项目里AGP 8.5、8.6、8.7 都能在 Gradle 8.13 下工作但 8.7 的表现更稳定尤其是在配置缓存和大规模资源编译场景下。如果你用的 AGP 版本过低最常见的问题不是构建直接失败而是某些 DSL 属性不存在或者在处理多模块项目时报“namespace not specified”。这些错误往往在升级后第一次执行assembleDebug时才暴露定位成本很高。选择 AGP 版本时我还建议关注一个细节AGP 本身对 Gradle 配置缓存的支持程度。老版本 AGP 内部很多任务没有适配配置缓存你显式开启后虽然不报错但缓存命中率极低等于开着开关却没省时间。升级 AGP 后这个问题会明显改善。3.2 namespace 迁移打包失败的第一个高频原因Gradle 8.13 配合新版 AGP对AndroidManifest.xml中的package属性是零容忍的。如果你还在 manifest 里写packagecom.example.app升级后打包会直接报错Setting the namespace via the package attribute in the source AndroidManifest.xml is no longer supported.这个错误的修复方式很明确把package属性从 manifest 里删掉然后在对应模块的build.gradle.kts里加namespaceandroid { namespace com.example.app }多模块项目尤其注意每个模块的namespace必须是唯一的否则资源类和 R 类会冲突。我在一个支付模块上遗漏了这个配置结果 IDE 不报错但打包后在运行时找不到支付网关的资源排查了很久。迁移 namespace 时还有一个隐藏的问题如果你的项目里用到了BuildConfig.APPLICATION_ID这个不会变因为 ApplicationId 仍然在defaultConfig里配置。但R类的包名会跟着 namespace 走。升级后代码中所有import com.example.app.R会被 IDE 自动修正但如果你用的是混淆后的资源引用就要格外注意资源 ID 的映射是否发生变化。3.3 BuildConfig 的开关与生成 API 变化新版 AGP 默认不再生成BuildConfig类。如果你在代码里用了BuildConfig.DEBUG或自定义字段升级到 Gradle 8.13 后可能遇到编译错误找不到 BuildConfig 类。这个问题的解决方案很简单在build.gradle.kts中显式开启android { buildFeatures { buildConfig true } }如果还需要往 BuildConfig 里添加自定义字段可以这样写android { defaultConfig { buildConfigField(String, API_BASE_URL, \https://api.example.com\) buildConfigField(boolean, LOG_ENABLED, true) } }我建议开启后顺便检查一下testOptions和unitTests的配置因为 BuildConfig 在某些测试场景下也会被依赖。之前项目里有个单元测试模块没开buildConfig导致测试运行时拿不到环境标识所有 HTTP 请求全打到 mock 服务器上这是升级后才发现的坑。3.4 资源链接器 aapt2 的行为变化Gradle 8.13 自带的 AGP 在调用 aapt2 时默认参数和行为会有些变化。最常见的问题出现在资源文件命名上。如果你项目里某张图片或布局文件的名字带了大写字母、空格或特殊符号升级前可能能过升级后会直接报error: file name must end with .xml or .pngaapt2 比老版本更严格地校验资源名规范。这个问题表面上是资源命名不规范实际上是你在升级时碰上了更严格的编译器。修复方式很暴力把资源文件重命名成小写字母和下划线的形式。如果文件名不规范的数量很多可以用 Android Studio 的 Refactor 功能批量改名改完后再检查R类引用。别偷懒只改文件名不搜索引用代码否则编译时到处是找不到符号的错误。还有一个 aapt2 相关的典型问题是--custom-package参数。某些多模块项目会用到资源分包老版本里你不指定package也能靠 manifest 里的 package 兜底但在 namespace 迁移后资源链接器需要明确指定包名。建议检查 build.gradle 中androidResources相关的配置android { androidResources { additionalParameters --custom-package additionalParameters com.example.library } }这段配置不是每个项目都需要但如果你的公共模块被多个 App 共用且资源引用方式特殊大概率会踩到这个。4. 构建提速配置缓存、构建扫描与并行构建的实测对比4.1 配置缓存值不值得开一轮实测数据先给结论值得开但前提是你的项目脚本已经适配好。我在这台 MacBook ProM1 Pro16GB上做了一个简单实测项目是 48 个模块的电商 App 壳工程。场景Gradle 8.2Gradle 8.13 未开配置缓存Gradle 8.13 开启配置缓存冷启动配置阶段38 秒27 秒12 秒增量构建改一行代码9 秒7 秒4 秒clean 后首次 assembleDebug2 分 45 秒2 分 51 秒2 分 40 秒热启动 assembleDebug1 分 30 秒1 分 20 秒45 秒可以看到配置缓存对增量构建和热启动的提升非常明显但对 clean 后首次构建帮助有限因为首次构建本来就需要完整执行所有任务。开启配置缓存的方式我在前面提过就是在gradle.properties里加一行org.gradle.configuration-cachetrue如果你用的是命令行可以临时加参数验证./gradlew :app:assembleDebug --configuration-cache如果构建顺利你会看到输出里多了类似 “Configuration cache entry stored” 的信息。如果构建失败日志里会明确说明哪个任务或哪段脚本不兼容。这时候先用下面命令临时关闭缓存继续排查./gradlew :app:assembleDebug --no-configuration-cache我建议在所有自定义 Task 都解决兼容性问题后再把配置缓存正式打开。不要一开始就全局开不然第一次构建失败时日志量会非常大很难定位。4.2 用构建扫描和 profile 定位性能瓶颈多人协作的大项目里构建慢不一定是 Gradle 版本问题可能是某些模块重复执行任务、资源链接器反复运行或者注解处理器没有开启增量模式。Gradle 8.13 内置的 profile 报告是很实用的工具执行./gradlew :app:assembleDebug --profile构建完成后在build/reports/profile/目录下会生成一个 HTML 报告。打开后能看到每个任务耗时、配置阶段时间和依赖解析时间。我通过这个报告发现项目里一个模块执行了 3 次mergeReleaseResources原因是变体数量过多且资源目录配置不当。如果你有构建扫描Build Scan的使用条件也可以用./gradlew :app:assembleDebug --scan注意新版构建扫描已经整合到 Develocity 生态里插件 ID 和配置方式和我以前用的不太一样。如果你只是本地排查profile 报告已经够用不需要额外部署云端服务。4.3 并行构建、缓存命中率与 JVM 参数调优Gradle 的并行构建和构建缓存在 8.13 里表现稳定但参数设置不合理反而会适得其反。我见过有团队把org.gradle.workers.max调到 16结果老机器直接卡死构建时间反而变长。我目前在这台 16GB 内存的机器上用的参数org.gradle.paralleltrue org.gradle.cachingtrue org.gradle.configureondemandfalse org.gradle.workers.max4 org.gradle.jvmargs-Xmx4g -Dfile.encodingUTF-8 -XX:UseParallelGC逐个解释一下org.gradle.paralleltrue是多模块并行构建对于模块之间没有强依赖的项目提升很大。org.gradle.cachingtrue是构建缓存尤其是 CI 环境里不同分支构建相同输入时可以复用缓存。org.gradle.configureondemandfalse这点容易被忽略按需配置有可能会跳过部分模块的配置导致任务列表不完整在 8.13 里我直接关掉。workers.max是最大并发 worker 数4 核 CPU 或内存不富裕的机器设置 4 就够了不要盲目调高。jvmargs里-Xmx4g是 Gradle 守护进程的最大堆内存项目大、模块多时可以调到 6g但别超过本机物理内存的一半。关于构建缓存有两点要提醒第一缓存命中和任务输入快照强相关如果你的构建脚本里用了不稳定的时间戳或随机数作为输入那缓存永远命中不了第二开启构建缓存后本地构建可能用到 CI 环境生成的缓存产物如果编译器版本不一致产物可能是无效的。所以尽量统一所有开发机和 CI 的 JDK、AGP、Kotlin 版本。4.4 增量注解处理Kapt/KSP 在 8.13 下的注意点如果你项目里用了很多注解处理器升级 Gradle 8.13 后会感受到明显的构建提速但前提是你正确配置了增量注解处理。老项目常用的 Kapt 在 8.13 环境下依然能跑但它和 Gradle 8.13 的配置缓存兼容性不是很好。Kapt 官方文档也建议逐步迁移到 KSP。如果你还在用 Kapt我建议在build.gradle.kts里把下面参数加上kapt { useBuildCache true correctErrorTypes true includeCompileClasspath false }includeCompileClasspath这个参数很关键。在 Gradle 8.13 里Kapt 默认不再把整个编译类路径交给处理器这样可以避免很多依赖重复处理的问题。如果你的注解处理器需要访问编译类路径千万别无脑设置成 true那会带来巨大的性能损耗。如果你已经用了 KSP注意 KSP 插件的版本需要和 Kotlin 版本匹配。我用的是 Kotlin 2.0.x对应的 KSP 版本号是2.0.21-1.0.25之类。下载错误版本的 KSP 会直接导致 Could not resolve 的报错这个问题我在升级后遇到过三次。5. 这份报错排查清单能救你于水火5.1 “Minimum supported Gradle version is …”升级后的第一次构建最容易遇到的就是这个报错。它通常长这样Minimum supported Gradle version is 8.2. Current version is 7.6.4.看似是你 Gradle 版本低了其实问题不一定在 Gradle而是你的 AGP 要求更高的 Gradle 版本。你升级了 Gradle Wrapper 却没升 AGP或者在旧 AGP 上强行用新 Gradle 执行任务。处理方式分两步。第一确认当前 AGP 版本./gradlew :app:properties | grep pluginVersion第二根据 AGP 版本要求调整 Gradle Wrapper。最稳妥的方式是手动修改gradle-wrapper.propertiesdistributionUrlhttps\://services.gradle.org/distributions/gradle-8.13-bin.zip然后重新同步。如果你想用命令行自动执行./gradlew wrapper --gradle-version 8.13 --distribution-type bin但注意如果你的旧 Gradle 版本太低可能不支持wrapper命令的某些参数。这时候手动改文件反而更快。5.2 “Could not find org.jetbrains.kotlin.android”升级后执行./gradlew可能会报Could not find org.jetbrains.kotlin.android:2.0.21.这个报错通常是插件仓库没配置对。新版 Android Studio 项目在settings.gradle.kts里用pluginManagement管理插件源你需要确保google()、mavenCentral()都在仓库列表里pluginManagement { repositories { google() mavenCentral() gradlePluginPortal() } }如果是国内网络环境mavenCentral()下载可能会比较慢可以使用阿里云公共镜像仓库来加速maven { url uri(https://maven.aliyun.com/repository/public) }需要注意插件仓库和依赖仓库是两个概念。pluginManagement.repositories里配的是插件和构建脚本依赖的仓库而模块的repositories配的是项目依赖所声明的第三方库仓库。我在实际问题排查中发现很多团队的libs.versions.toml里 Kotlin 版本号写错了或者写了一个尚不存在的版本也会导致这个报错。检查libs.versions.toml的版本号是否真实存在是排查这个问题的第一动作。5.3 配置缓存导致的 NoClassDefFoundError配置缓存开启后有一种报错非常典型第一次构建成功第二次构建却报NoClassDefFoundError。原因是配置缓存序列化了某个自定义 Task 的状态但反序列化时找不到对应的类。这类问题往往出现在“任务实现类写在构建脚本里”的场景。比如你直接在build.gradle.kts中写了一个open class MyTask : DefaultTask()第一次构建时类加载没问题第二次构建从缓存恢复时Gradle 无法在原有上下文中重新加载这个类于是抛错。解决思路有两个。一是把自定义任务类挪到buildSrc或者在独立模块中保证类可以被标准类加载器管理。二是给任务加上DisableCachingByDefault注解明确告诉 Gradle 这个任务不参与配置缓存序列化import org.gradle.work.DisableCachingByDefault DisableCachingByDefault(because 暂未适配配置缓存) abstract class MyTask : DefaultTask() { TaskAction fun run() { // do something } }如果报错发生在某个依赖库自带的插件上你没法直接修改插件源码这时候最快的处理方式是给该插件的任务加上“不启用配置缓存”的约束或者干脆先关闭配置缓存等插件版本更新。我在这个坑上耗费过整整一个下午后来发现只是打了一个动态代理类不适合序列化。5.4 依赖冲突 TopException 与 dependencyInsight升级 Gradle 8.13 后依赖冲突的报错展示方式也有变化。以前你会发现冲突时构建失败并打印所有冲突坐标现在很多情况是只提示 TopException让你自己去查依赖树。遇到这种情况先运行./gradlew :app:dependencyInsight --dependency okhttp --configuration debugRuntimeClasspath这个命令会显示okhttp在debugRuntimeClasspath中的来源和冲突版本。如果你不确定配置名称可以先跑./gradlew :app:dependencies --configuration debugRuntimeClasspath依赖树打印出来很长建议保存到文件里慢慢看./gradlew :app:dependencies --configuration debugRuntimeClasspath deps.txt定位到冲突来源后通常的解决方式是强制指定版本configurations.all { resolutionStrategy { force(com.squareup.okhttp3:okhttp:4.12.0) } }或者单独排除某个模块传递依赖implementation(com.squareup.retrofit2:retrofit:2.9.0) { exclude(group com.squareup.okhttp3, module okhttp) }升级后我建议把项目里所有的exclude和force都审核一遍因为 Gradle 8.13 对依赖图的校验变严格了以前写得很宽泛的 exclude 模式现在可能会误伤新引入的模块。5.5 周边问题模拟器 WHPX、SDK 路径、中文汉化、帮助文档升级 Android Studio 到新版后很多人会顺手遇到模拟器问题。Windows 上最常见的报错是“Windows Hypervisor Platform API”启动失败。这个跟 Gradle 8.13 没有直接关系但新版 Android Studio 安装时会更新 SDK 和 Emulator 组件导致之前的 HAXM 驱动失效。我的处理方式是先到“控制面板 - 程序 - 启用或关闭 Windows 功能”里确认“Windows 虚拟机监控程序平台”和“Hyper-V”两个选项一致勾选重启后再试。如果之前装过 Intel HAXM新版模拟器驱动建议改用 Android Studio 自带的“Android Emulator hypervisor driver”在 SDK Manager 的 SDK Tools 里下载。AMD 处理器用户直接用 WHPX 支持不要装 HAXM。关于 Android Studio 中文汉化这个问题热度很高。官方其实没有提供内置的语言切换想要中文界面一般靠安装中文语言包插件。我建议谨慎处理因为第三方汉化插件对 IDE 版本要求很严格插件版本不匹配时轻则菜单空白重则 IDE 启动失败。更重要的是汉化包如果覆盖了 IDE 自带的 lib 目录可能会干扰 Gradle 插件加载这时候你再回头排查构建问题会非常混乱。新版 Android Studio 的帮助文档入口也变了。以前直接在 Help 菜单里能找到一堆链接新版整合成了“Help Documentation”打开后是官方在线文档站。如果你在升级过程中想查某个 API直接点这个入口比去搜索引擎找“Gradle 8.13 中文教程”靠谱得多。5.6 IDE 的 Gradle 面板里 Task“消失”的完全指南这个问题我再展开说说因为它太容易让人误判了。升级后在 Android Studio 右侧 Gradle 面板里看到的任务数量锐减常见原因有三个。第一构建变体选择导致任务被过滤。新版 AGP 在同步时会读取当前构建变体只展示该变体相关的任务。如果你选择的是debug变体那么和release相关的任务比如bundleRelease、assembleRelease在面板里可能直接不显示。解决方式在 Build Variants 窗口切到其他变体再刷新一次 Gradle 面板。第二任务按需注册Task Configuration Avoidance生效。Gradle 8.13 默认大量使用registerAPI很多任务在配置阶段不初始化只有执行时才会出现。IDE 面板展示的是配置阶段任务图自然看起来少了。要验证任务真的存在用命令行跑./gradlew :app:tasks --all这个命令会触发更完整的任务注册。第三面板低于项目同步状态。升级 Gradle 版本后如果 IDE 没有自动同步任务列表可能还是旧状态。手动点击 Gradle 面板的刷新按钮或执行一遍 Sync就可以解决。6. 我的实测结论不分项目类型乱升级迟早要返工6.1 升级前后的真实构建耗时对比我用一个公司内部的中型项目做了完整升级对比。项目是 48 个模块的电商 App依赖非常多资源文件数量超过 20000 个用 Gradle 8.2 到 8.13 的整个流程跑了三天。完整数据在上面表格里已经给过这里再说两个细节。一个是clean后的首次构建8.13 并没有比 8.2 快多少甚至有时候慢一点因为新版本的配置缓存需要生成缓存条目第一次构建会额外付出序列化的成本。另一个是增量构建的提升非常明显如果你平时工作流是改一行代码然后热部署那升级到 8.13 后感受会非常直观。不过这些数据只代表我这个项目的实际情况。不同项目的模块数量、依赖复杂度、资源文件规模都不一样建议你升级后自己跑一遍 profile别拿别人的数据当决策依据。6.2 三类项目适合立即升级三类建议暂缓根据我这段时间的实际体验下面这些项目可以放心升级第一新项目。没有任何历史包袱直接从 Gradle 8.13 AGP 8.7 起步各种新特性开满根本不需要迁移。第二中小型项目模块数量少于 10 个构建脚本简单。升级出问题也能快速定位配置缓存适配成本低。第三已经用了 Kotlin DSL 和 Version Catalog 的现代化项目。这类项目离官方推荐的状态最近升级基本是平滑的。相反下面这些项目我建议暂缓第一深度依赖 Kapt 并且没有改造计划的项目。Kapt 在 Gradle 8.13 下虽然没有被禁用但和配置缓存的兼容性会影响构建体验你需要先迁移到 KSP 才行。第二老插件特别多的项目。比如还在用旧版 ButterKnife、旧版 EventBus 注解处理器这类插件与增量注解处理的兼容性很差。升级后构建失败概率非常高而且报错信息不直观。第三模块数量极多、构建逻辑复杂、构建脚本里大量使用project.afterEvaluate的项目。这类项目对配置缓存的适配成本极高建议先升级到 8.10 过渡不要直接冲击 8.13。6.3 升级后的两个“后悔药”操作万一升级后问题太多别慌有两个快速回退的操作。第一个是恢复 Gradle Wrapper。如果你备份过gradle-wrapper.properties直接还原文件然后执行一遍 Sync 即可。如果没有备份可以通过 IDE 左侧 Project 面板找到 Gradle Scripts 下的gradle-wrapper.properties手动把 distributionUrl 改回旧版本号。注意改完后一定要再执行一次./gradlew --version确认 wrapper 重新下载了对应版本。第二个是关闭新特性。把gradle.properties里的org.gradle.configuration-cachetrue、org.gradle.paralleltrue、org.gradle.cachingtrue全部注释掉让项目回到“只要结果正确”的状态。这样虽然构建慢一点但能保证大家在团队协作中不会因为构建环境不一致而对不上结果。7. 最后聊点版本心态构建工具升级不是技术债是知识税我见过太多团队对 Gradle 升级的态度是“能用就行”。结果就是项目一直停留在 Gradle 6.x、7.x每次有同事想用新特性都会被拦下来。但工具链这东西你不跟进迟早要连本带利地还。我个人在这次升级中最大的收获不是构建时间缩短了多少而是逼着自己把那些“以前能跑但不知道为什么能跑”的构建脚本清理了一遍。配置缓存让我们必须严谨地思考任务输入和输出Kotlin DSL 让我们必须明确每个属性的真实类型AGP 版本矩阵推动我们重新审视模块划分是否合理。这些都不是单纯的版本号问题而是工程能力层面的提升。如果你现在正在为升级 Gradle 8.13 发愁我最后再分享两个小技巧。第一遇到问题时先把--stacktrace和--info打开再跑一次./gradlew :app:assembleDebug --stacktrace --info输出量会很大但日志里藏着的因果链往往比搜索引擎里的答案更直接。大多数人报错只知道贴最后一段日志这远远不够一定要往上翻找到第一次出现 “What went wrong” 的地方。第二团队升级时尽量固定一个“基准环境”。把所有成员统一的 JDK 版本、Android Studio 版本、Gradle 版本、AGP 版本列成一张表贴在项目 README 里。我在这次升级中遇到的 80% 的“奇奇怪怪的报错”最后都指向某个同事的 JDK 版本和大家不一样。工具链升级这件事踩坑不可怕可怕的是每次踩坑都靠搜索解决却从不停下来想想为什么。Gradle 8.13 会把过去几年你欠下的构建配置债一次性地摆在台面上还债的过程很痛苦但还完之后你会发现整个项目的构建链路从来没有这么清晰过。