---
description: 修复 Android 和 KMP 项目的 Gradle 构建错误
---

# Gradle 构建修复

逐步修复 Android 和 Kotlin 多平台项目的 Gradle 构建和编译错误。

## 步骤 1：检测构建配置

识别项目类型并运行相应的构建：

| 指示符 | 构建命令 |
|-----------|---------------|
| `build.gradle.kts` + `composeApp/` (KMP) | `./gradlew composeApp:compileKotlinMetadata 2>&1` |
| `build.gradle.kts` + `app/` (Android) | `./gradlew app:compileDebugKotlin 2>&1` |
| `settings.gradle.kts` 包含模块 | `./gradlew assemble 2>&1` |
| 配置了 Detekt | `./gradlew detekt 2>&1` |

同时检查 `gradle.properties` 和 `local.properties` 以获取配置信息。

## 步骤 2：解析并分组错误

1. 运行构建命令并捕获输出
2. 将 Kotlin 编译错误与 Gradle 配置错误分开
3. 按模块和文件路径分组
4. 排序：先处理配置错误，然后按依赖顺序处理编译错误

## 步骤 3：修复循环

针对每个错误：

1. **读取文件** — 错误行周围的完整上下文
2. **诊断** — 常见类别：
   * 缺少导入或无法解析的引用
   * 类型不匹配或不兼容的类型
   * `build.gradle.kts` 中缺少依赖项
   * Expect/actual 不匹配 (KMP)
   * Compose 编译器错误
3. **最小化修复** — 解决错误所需的最小改动
4. **重新运行构建** — 验证修复并检查新错误
5. **继续** — 处理下一个错误

## 步骤 4：防护措施

如果出现以下情况，请停止并询问用户：

* 修复引入的错误比解决的错误多
* 同一错误在 3 次尝试后仍然存在
* 错误需要添加新的依赖项或更改模块结构
* Gradle 同步本身失败（配置阶段错误）
* 错误出现在生成的代码中（Room、SQLDelight、KSP）

## 步骤 5：总结

报告：

* 已修复的错误（模块、文件、描述）
* 剩余的错误
* 引入的新错误（应为零）
* 建议的后续步骤

## 常见的 Gradle/KMP 修复方案

| 错误 | 修复方法 |
|-------|-----|
| `commonMain` 中无法解析的引用 | 检查依赖项是否在 `commonMain.dependencies {}` 中 |
| Expect 声明没有 actual 实现 | 在每个平台源码集中添加 `actual` 实现 |
| Compose 编译器版本不匹配 | 在 `libs.versions.toml` 中统一 Kotlin 和 Compose 编译器版本 |
| 重复类 | 使用 `./gradlew dependencies` 检查是否存在冲突的依赖项 |
| KSP 错误 | 运行 `./gradlew kspCommonMainKotlinMetadata` 重新生成 |
| 配置缓存问题 | 检查是否存在不可序列化的任务输入 |