React Native Android构建失败：解析com.facebook.react.settings插件报Zip异常

API 探路者

2026-6-14

React Native Android构建失败：com.facebook.react.settings解析错误（zip END header not found）

错误详情

构建时触发以下失败：

FAILURE: Build completed with 2 failures.
1: Task failed with an exception.
位置：设置文件 D:\Project\Git Project\ReactNative\projectname\reactnativeapp\android\settings.gradle 第2行
问题详情：解析插件 [id: 'com.facebook.react.settings'] 出错
配置项目 ':gradle-plugin:react-native-gradle-plugin' 时出现问题。
java.util.zip.ZipException: zip END header not found

解决步骤

清理Gradle全局缓存
该错误多因Gradle缓存的依赖包损坏导致，找到对应目录删除缓存：
- Windows：删除 C:\Users\<你的用户名>\.gradle\caches 文件夹
- Mac/Linux：删除 ~/.gradle/caches 文件夹
清理项目本地构建文件与依赖
1. 删除项目根目录下的 node_modules 文件夹
2. 删除项目内 android/build 和 android/app/build 文件夹
3. 重新安装依赖：执行 npm install 或 yarn install
重新执行构建
进入android目录，先清理缓存再构建：
```
cd android
./gradlew clean
./gradlew assembleDebug
```
或直接用React Native命令启动：
```
npx react-native run-android
```

检查网络与镜像配置
若重新下载依赖仍失败，大概率是网络不稳定导致包下载不完整：

切换至稳定网络环境

配置国内Gradle镜像（修改项目 android/build.gradle）：

buildscript {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/jcenter' }
        maven { url 'https://maven.aliyun.com/nexus/content/groups/public' }
    }
}
allprojects {
    repositories {
        maven { url 'https://maven.aliyun.com/repository/google' }
        maven { url 'https://maven.aliyun.com/repository/jcenter' }
        maven { url 'https://maven.aliyun.com/nexus/content/groups/public' }
    }
}