Flutter项目运行报错ZipException: zip END header not found原因及解决

错误原因 #

从报错栈可以明确，这是Gradle包装器解压Gradle分发压缩包时触发的异常，核心问题是Gradle的zip压缩包损坏或不完整，常见触发场景：

• 网络不稳定导致Gradle压缩包下载中断，文件未完全获取
• 本地Gradle缓存的zip文件因存储故障、异常关机等原因损坏
• 权限不足导致zip文件写入时未完整保存

修复方案 #

方案1：清理本地Gradle缓存并重新下载 #

• 找到项目内的.gradle/wrapper/dists目录，删除对应Gradle版本的文件夹
• 或者找到全局Gradle缓存目录：
  • Windows：C:\Users\<你的用户名>\.gradle\wrapper\dists
  • Mac/Linux：~/.gradle/wrapper/dists
    删除其中对应版本的文件夹
• 重新执行flutter run，Gradle会自动重新下载完整的压缩包并解压

方案2：手动下载替换压缩包 #

• 打开项目中gradle/wrapper/gradle-wrapper.properties文件，找到distributionUrl字段，复制对应的下载链接（比如https://services.gradle.org/distributions/gradle-7.4-all.zip）
• 手动下载该zip文件，放到全局或项目的dists目录下对应版本的文件夹中
• 再次执行flutter run即可

方案3：修复目录权限（仅Mac/Linux） #

如果是权限问题导致文件写入不完整，执行以下命令赋予Gradle缓存目录读写权限：

sudo chmod -R 755 ~/.gradle

原始报错信息 #

Exception in thread "main" java.util.zip.ZipException: zip END header not found
    at java.base/java.util.zip.ZipFile$Source.zerror(ZipFile.java:1581)
    at java.base/java.util.zip.ZipFile$Source.findEND(ZipFile.java:1476)
    at java.base/java.util.zip.ZipFile$Source.initCEN(ZipFile.java:1483)
    at java.base/java.util.zip.ZipFile$Source.<init>(ZipFile.java:1288)
    at java.base/java.util.zip.ZipFile$Source.get(ZipFile.java:1251)
    at java.base/java.util.zip.ZipFile$CleanableResource.<init>(ZipFile.java:732)
    at java.base/java.util.zip.ZipFile$CleanableResource.get(ZipFile.java:849)
    at java.base/java.util.zip.ZipFile.<init>(ZipFile.java:247)
    at java.base/java.util.zip.ZipFile.<init>(ZipFile.java:177)
    at java.base/java.util.zip.ZipFile.<init>(ZipFile.java:191)
    at org.gradle.wrapper.Install.unzip(Install.java:214)
    at org.gradle.wrapper.Install.access$600(Install.java:27)
    at org.gradle.wrapper.Install$1.call(Install.java:74)
    at org.gradle.wrapper.Install$1.call(Install.java:48)
    at org.gradle.wrapper.ExclusiveFileAccessManager.access(ExclusiveFileAccessManager.java:65)
    at org.gradle.wrapper.Install.createDist(Install.java:48)
    at org.gradle.wrapper.WrapperExecutor.execute(WrapperExecutor.java:128)
    at org.gradle.wrapper.GradleWrapperMain.main(GradleWrapperMain.java:61)
Exception: Gradle task assembleDebug failed with exit code 1

内容的提问来源于stack exchange，提问作者Gunjon Roy