React Native Android构建:expo-file-system:compileDebugKotlin失败

• React Native项目iOS端可正常编译，Android端构建失败
• Android模拟器可正常启动，排除Android基础开发环境配置问题
• 构建中断节点为:expo-file-system:compileDebugKotlin任务，提示Kotlin编译错误
• 当前项目根目录build.gradle版本配置：

buildscript {
    ext {
        buildToolsVersion = "29.0.3"
        minSdkVersion = 21
        compileSdkVersion = 30
        targetSdkVersion = 30
    }
}

• 核心报错堆栈：

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':expo-file-system:compileDebugKotlin'.
> Compilation error. See log for more details

* Try:
Run with --info or --debug option to get more log output. Run with --scan to get full insights.

* Exception is:
org.gradle.api.tasks.TaskExecutionException: Execution failed for task ':expo-file-system:compileDebugKotlin'.
Caused by: org.gradle.api.GradleException: Compilation error. See log for more details

按优先级依次操作，绝大多数场景下前两步即可解决问题：

1. 修正Android构建版本配置 #

当前配置的compileSdkVersion = 30版本过低，近2年发布的expo-file-system版本最低要求compileSdkVersion为31，部分新版本要求33，同时需要固定全局Kotlin版本，避免各依赖自行拉取不兼容的Kotlin版本引发编译错误。
修改根目录下android/build.gradle的buildscript配置块为：

buildscript {
    ext {
        buildToolsVersion = "33.0.2"
        minSdkVersion = 21
        compileSdkVersion = 33
        targetSdkVersion = 33
        kotlinVersion = "1.8.22"
    }
}

2. 全量清理缓存后重新构建 #

版本配置修改完成后，在项目根目录依次执行以下命令清理旧构建缓存、重装依赖：

# 清理Android构建产物缓存
cd android && ./gradlew clean && cd ..
# 删除现有依赖目录
rm -rf node_modules
# 选择项目对应包管理工具重新安装依赖
npm install
# yarn install
# pnpm install
# 重新触发Android构建
npx react-native run-android

3. 对齐expo-file-system的兼容版本 #

如果上述操作后依然报错，大概率是安装的expo-file-system版本和当前React Native版本不匹配：

• React Native版本为0.66~0.70区间的项目，安装适配稳定版：执行npm install expo-file-system@15.1.1
• React Native版本为0.71及以上的项目，可升级到最新稳定版，同时保证所有expo生态依赖的大版本一致，禁止跨大版本混用（比如expo-modules-core使用46.x版本、expo-file-system使用49.x版本的组合必然出现编译错误）

4. 定位具体编译错误 #

如果以上操作都未解决问题，现有简略报错没有给出具体错误点，进入android目录执行带详细日志的构建命令，即可看到具体的Kotlin编译错误原因：

cd android
./gradlew assembleDebug --info

从过往排错经验看，剩余的常见错误原因包括：

• 本地Gradle缓存损坏：删除用户目录下的.gradle/caches文件夹后重新构建即可
• 依赖重复引入：多个第三方库同时引入了不同版本的expo相关依赖，可通过./gradlew app:dependencies查看依赖树排除冲突
• Gradle插件版本过低：将Android项目的Gradle插件版本升级到7.3+即可适配新的Kotlin版本

内容的提问来源于stack exchange，提问作者Swift Sharp