PAYATHON 2026

Expo EAS 构建 Android APK 时在 Run gradlew 阶段失败，如何排查？

数据小许

现有配置已经指定生成 Android APK。Run gradlew 是失败阶段的名称，仅凭这一信息和 package.json 无法确定根因。应先找到 Gradle 的具体报错，再检查依赖兼容性。目前没有依据认定问题来自 Windows 文件编码或缓存。

APK 构建配置是否正确？

buildType: "apk" 和 gradleCommand: ":app:assembleRelease" 都是官方支持的 APK 构建配置。对于没有自定义 Gradle task 或 product flavors 的常规项目，保留 buildType 即可，无需同时指定命令。Expo APK 构建说明

可以只将 eas.json 中的 build.preview 改为以下内容，其余配置保留：

{
  "distribution": "internal",
  "android": {
    "buildType": "apk"
  }
}

然后执行：

eas build --platform android --profile preview

这样做只是为了简化配置。原来的 :app:assembleRelease 本身不能证明配置有误，删除它也不能保证解决编译失败。

先从日志中找出失败的任务

打开失败构建的详情页，展开 Run gradlew，保留以下内容及其前后的日志：

  • Execution failed for task 后面的任务名称。
  • What went wrong 下的错误说明。
  • 相关的 Caused by 信息。
  • 更早出现的编译错误、缺失依赖或模块解析错误。

不要只截取最后的 BUILD FAILED，也不要把所有 [stderr] 输出都当成错误。Expo 官方说明，警告也可能写入 stderr，较早出现的有效错误通常更有排查价值。Expo 构建排错说明

具体怎么处理取决于日志。如果日志指出某个原生模块的 Java 或 Kotlin 编译失败，就检查该模块的 Android 实现与兼容性；如果提示 Unable to resolve module，则检查导入路径、文件是否被上传，以及依赖是否安装。这些只是排查方向，不能据此认定当前项目属于其中某一种情况。

检查 Expo SDK 和依赖版本

在项目根目录执行：

npx expo-doctor
npx expo install --check

expo-doctor 用于检查项目配置和兼容性问题，expo install --check 用于检查依赖是否符合当前 Expo SDK 的版本要求。Expo 构建排错说明、Expo CLI 文档

这份依赖列表中，可以优先核对：

  • expo、react、react-native 及各个 expo-* 包是否匹配当前 SDK。
  • react-native-reanimated 与 react-native-worklets 是否满足彼此的兼容要求。
  • 如果错误日志涉及 @react-native-voice/voice 等原生模块，再检查该模块的 Android 配置和支持范围。

不要仅凭版本号看起来较新或较旧就认定不兼容，也不要直接将某个原生依赖当成故障来源。

如果检查明确报告了版本不匹配，先保存当前改动，再按检查结果调整。需要由 Expo 对齐其支持的依赖版本时，可以使用：

npx expo install --fix

该命令会修改依赖。运行后应检查 package.json 和所用包管理器的锁文件变化，再重新运行检查。第三方原生模块仍需单独核对兼容性。Expo CLI 文档

Windows 上如何进一步定位？

此前 .xcode.env 的编码修复解决的是 iOS 构建问题，不能据此推断 Android 也有相同原因。当前命令没有使用 --local，因此也不能直接把云端 Gradle 失败归因于 Windows 本机的 Java 或 Android SDK。

如果已经配置好本机 Android 开发环境，且项目中存在可用于构建的 android 目录，可以在 PowerShell 中执行对应的 release task，获取更详细的堆栈：

cd android
.\gradlew.bat :app:assembleRelease --stacktrace

如果项目使用自定义 flavors，应改用云端实际执行的 task。本地构建有助于定位问题，但只有在环境和输入条件相近时，其结果才适合与云端比较。

清缓存后仍失败，下一步是什么？

--clear-cache 可以用于排除缓存干扰，但无法修复版本不兼容、源码编译错误或缺失配置。既然已经尝试过清缓存，接下来应记录具体失败任务和错误上下文。

修复日志指向的问题后，重新执行 preview 构建。构建成功后，可以从构建详情页取得 APK，交给 Android 测试设备安装。Expo APK 安装说明

目前需要补充完整的 Gradle 错误片段和依赖检查输出。在获得这些信息之前，可以确认 APK 配置方向正确，但还不能确定某个依赖必须升级、降级或删除。

备注：内容仅供参考。