解决 Android 构建报错：Unable to delete file .../file-map.txt

问题现象

在一次 Android 工程构建过程中，出现如下报错：

Unable to delete file
'/Users/demo/Workspace/sample-android/app/build/intermediates/source_set_path_map/debug/mapDebugSourceSetPaths/file-map.txt'

报错发生在构建清理或资源映射阶段，导致编译中断。示例路径仅为模拟，实际路径以本地工程为准。

原因分析

这类报错通常不是业务代码或 Gradle 配置错误，而是构建缓存文件被进程占用，文件句柄未释放。

常见占用来源包括：

• 未退出的 Gradle Daemon；
• Android Studio / IntelliJ IDEA / VS Code 等编辑器仍在索引工程；
• IDE 与命令行同时触发构建，竞争访问 build 目录；
• 安全软件实时扫描锁定临时文件。

核心处理思路很简单：先停止占用进程，再清理构建缓存，最后重新构建。

解决方案

以下步骤实测有效，按顺序执行即可。

1. 关闭相关 IDE 和编辑器

完全退出 Android Studio、IntelliJ IDEA、VS Code 等可能打开该工程的工具，避免后台索引继续锁定文件。

2. 停止 Gradle Daemon

进入 Android 工程根目录，也就是包含 gradlew 的目录：

cd /Users/demo/Workspace/sample-android
./gradlew --stop

3. 清理项目构建缓存

在工程根目录执行：

rm -rf app/build
rm -rf .gradle

如果工程包含多个模块，可按需清理对应模块的 build 目录。这里只清理项目级缓存，不涉及全局 Gradle 缓存。

4. 重新构建

命令行重新构建：

./gradlew clean assembleDebug

也可以回到 IDE 执行 Clean Project 后重新 Rebuild Project。

5. 兜底排查

如果仍然报错，可重启电脑释放文件句柄。也可以定位占用进程：

lsof | grep file-map.txt

找到对应 PID 后结束进程，或直接重启系统。

验证结果

重新构建成功后，file-map.txt 会在构建过程中重新生成，报错消失，工程可正常打包。

预防建议

• 避免 IDE 与命令行同时构建同一工程；
• 构建前可先执行 ./gradlew --stop；
• 出现类似缓存文件删除失败时，优先清理 app/build 和 .gradle；
• 不要一上来修改业务代码或 Gradle 插件版本，先排除进程占用问题。

总结

Unable to delete file .../file-map.txt 本质是构建缓存文件被占用。按"退出 IDE → 停止 Gradle Daemon → 清理 app/build 和 .gradle → 重新构建"的顺序处理，通常可以快速解决。