Android Build Tools 31.0.0 已损坏错误解决方案

问题描述

当使用 Android Studio 4.2.2 或更高版本创建新项目时，构建或运行项目时可能会遇到以下错误：

已安装的 Build Tools 修订版 31.0.0 已损坏。请使用 SDK 管理器删除并重新安装。

这个问题通常发生在使用 Android SDK Build Tools 31.0.0 版本时，即使尝试重新安装该版本或降级到旧版本，错误仍然存在。

根本原因

这个问题的根本原因是 Android SDK Build Tools 31.0.0 版本中缺少了两个关键文件：

1. dx.bat（Windows）或 dx（macOS/Linux）
2. dx.jar

这些文件在较新版本中已被重命名为：

• d8.bat（Windows）或 d8（macOS/Linux）
• d8.jar

但某些工具链仍然期望找到旧文件名，导致构建过程失败。

解决方案

以下是几种有效的解决方案，从推荐的最佳实践到临时解决方法。

方案一：升级 Android Gradle 插件（推荐）

最佳实践

这是最推荐的长期解决方案，无需修改 SDK 文件。

1. 打开项目级别的 build.gradle 文件
2. 更新 Android Gradle 插件版本：

// 项目级别的 build.gradle
dependencies {
    classpath "com.android.tools.build:gradle:7.0.2" // 或更高版本
}

3. 更新 Gradle 包装器版本（gradle-wrapper.properties）：

distributionUrl=https\://services.gradle.org/distributions/gradle-7.0.2-bin.zip

4. 同步项目并重新构建

方案二：重命名文件（临时解决方案）

如果无法立即升级 Gradle 插件，可以手动修复缺失的文件。

注意

这是临时解决方案，每次安装新的 Build Tools 可能需要重复此操作。

Windows 系统

1. 打开文件资源管理器，导航到：

   C:\Users\[用户名]\AppData\Local\Android\Sdk\build-tools\31.0.0

   提示

   AppData 是隐藏文件夹，需要在查看选项中启用"隐藏的项目"

2. 将 d8.bat 重命名为 dx.bat

3. 进入 lib 子文件夹，将 d8.jar 重命名为 dx.jar

macOS/Linux 系统

打开终端并执行以下命令：

cd ~/Library/Android/sdk/build-tools/31.0.0
mv d8 dx
cd lib
mv d8.jar dx.jar

方案三：使用符号链接（跨平台方案）

对于需要自动化部署的环境（如 CI/CD），可以使用符号链接：

Windows

mklink C:\Users\username\AppData\Local\Android\Sdk\build-tools\31.0.0\dx.bat C:\Users\username\AppData\Local\Android\Sdk\build-tools\31.0.0\d8.bat
mklink C:\Users\username\AppData\Local\Android\Sdk\build-tools\31.0.0\lib\dx.jar C:\Users\username\AppData\Local\Android\Sdk\build-tools\31.0.0\lib\d8.jar

macOS/Linux

cd ~/Library/Android/sdk/build-tools/31.0.0
ln -s d8 dx
cd lib
ln -s d8.jar dx.jar

方案四：降级 Build Tools 版本

如果上述方法都不适用，可以考虑降级到较早的 Build Tools 版本：

1. 在 Android Studio 中打开 SDK 管理器
2. 取消选中 Build Tools 31.0.0
3. 安装较早版本（如 30.0.3）
4. 更新模块的 build.gradle 文件：

android {
    compileSdkVersion 30
    buildToolsVersion "30.0.3"
    // ...
}

方案五：CI/CD 环境解决方案

对于 Azure DevOps、CircleCI 等持续集成环境，可以在构建前添加修复步骤：

# CircleCI 示例
- run:
    name: 修复 Build Tools 31 缺失的 DX 文件
    command: |
      cd $ANDROID_HOME/build-tools/31.0.0 && mv d8 dx && cd lib && mv d8.jar dx.jar

预防措施

为了避免将来遇到类似问题：

1. 保持工具更新：定期更新 Android Studio、Gradle 插件和 Build Tools
2. 使用最新稳定版：避免使用预览版或RC版进行生产开发
3. 检查兼容性：在升级 SDK 版本时，确保所有工具链兼容

总结

Android Build Tools 31.0.0 "已损坏"错误通常是由于文件命名变更引起的兼容性问题。推荐优先采用升级 Android Gradle 插件的方案，这是最彻底和长期的解决方案。如果暂时无法升级，可以使用文件重命名或符号链接作为临时解决方案。

提示

无论采用哪种方案，都建议在修改后清理并重新构建项目：

• 选择菜单：Build → Clean Project
• 然后：Build → Rebuild Project

通过以上任一方法，您应该能够解决 Build Tools 31.0.0 已损坏的错误，并顺利构建和运行 Android 项目。