# 错误：无法将请求的类放入单个 dex 文件中。请尝试提供 main-dex-list。

- **ID:** `android/multidex-main-dex-list-error`
- **领域:** android
- **类别:** build_error
- **验证级别:** ai_generated
- **修复率:** 90%

## 根因

应用中的方法数超过了每个 dex 文件的 64K 限制，且构建系统无法确定哪些类必须进入主 dex。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| Android 5.0 (API 21) | active | — | — |
| Android 6.0 (API 23) | active | — | — |
| Android Gradle Plugin 7.0 | active | — | — |
| Android Gradle Plugin 8.0 | active | — | — |

## 解决方案

1. ```
   在应用根目录创建 main-dex-list.txt 文件，列出必须放入主 dex 的类（例如 Application 子类、Activity、Service）。然后在 build.gradle 中配置：'multiDexKeepProguard file('main-dex-list.txt')'。
   ```
2. ```
   在 build.gradle 中启用 multidex：'defaultConfig.multiDexEnabled true' 并添加 multidex 依赖：'implementation 'androidx.multidex:multidex:2.0.1''。对于目标 API < 21 的应用，确保 Application 类继承 MultiDexApplication。
   ```
3. ```
   使用 ProGuard 或 R8 进行代码压缩，移除未使用的代码，将总方法数减少到 64K 限制以下。
   ```

## 无效尝试

- **** — For apps with very large method counts, automatic resolution may fail if certain classes must be in the primary dex for startup. (60% 失败率)
- **** — This is an extreme measure that breaks functionality; the real fix is proper multidex configuration. (90% 失败率)