解决 Flutter Gradle 下载报错：修改默认 distributionUrl

一、问题背景

在创建或运行 Flutter 项目时，经常会遇到 Gradle 下载缓慢、超时或失败的问题，这是因为默认的 Gradle 分发地址位于国外，国内网络环境下访问不稳定。本文将从临时修改当前项目和永久修改 Flutter 模板两个维度，提供完整解决方案。

二、临时方案：修改当前项目的 Gradle 分发地址

适用于已有项目，快速解决当前构建问题。

1. 使用国内镜像源（推荐）

找到项目中的android/gradle/wrapper/gradle-wrapper.properties文件，将distributionUrl替换为国内镜像地址（如腾讯云、阿里云）：

# 原地址（注释掉） # distributionUrl=https\://services.gradle.org/distributions/gradle-8.12-all.zip # 替换为腾讯云镜像 distributionUrl=https://mirrors.cloud.tencent.com/gradle/gradle-8.12-all.zip

2. 检查 Gradle 版本一致性

确保distributionUrl中的 Gradle 版本与项目要求一致，可在android/build.gradle中查看所需版本：

dependencies { classpath 'com.android.tools.build:gradle:7.3.0' }

若版本不匹配，需下载对应版本的 Gradle 包并更新distributionUrl。

3. 本地配置 Gradle（离线可用）

若网络问题无法解决，可手动下载 Gradle 压缩包，配置为本地路径：

distributionUrl=file:///D:/dev-tools/gradle/gradle-8.12-all.zip

三、修改 Flutter SDK 模板（一劳永逸）

适用于新建项目，避免每次创建都要手动修改distributionUrl。

1. 找到 Flutter SDK 模板文件

进入 Flutter SDK 安装目录，定位到以下路径：

flutter\packages\flutter_tools\templates\app_shared\android.tmpl\gradle\wrapper

找到文件：gradle-wrapper.properties.tmpl

2. 编辑模板文件

打开文件，注释掉原有的distributionUrl，替换为国内镜像地址：

distributionBase=GRADLE_USER_HOME distributionPath=wrapper/dists zipStoreBase=GRADLE_USER_HOME zipStorePath=wrapper/dists ## 注释掉官方默认地址 ## distributionUrl=https\://services.gradle.org/distributions/gradle-{{gradleVersion}}-all.zip ## 更改为国内镜像分发地址（保留变量 {{gradleVersion}} 以适配版本） distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-{{gradleVersion}}-all.zip

3. 生效验证

保存文件后，重新创建 Flutter 项目，新项目的android/gradle/wrapper/gradle-wrapper.properties会自动使用国内镜像地址，无需再次手动修改。

四、常见问题排查

1. 版本不匹配报错：确保distributionUrl中的 Gradle 版本与android/build.gradle中com.android.tools.build:gradle版本兼容。
2. 镜像地址失效：若腾讯云镜像不可用，可替换为阿里云镜像：

   properties

   distributionUrl=https://maven.aliyun.com/repository/gradle-distributions/gradle-{{gradleVersion}}-all.zip

3. 离线模式：若完全无网络，可使用本地路径配置，提前下载好对应版本的 Gradle 压缩包。

五、总结

• 临时修复：针对已有项目，直接修改gradle-wrapper.properties，快速解决当前构建问题。
• 永久生效：修改 Flutter SDK 模板文件，新建项目自动使用国内镜像，避免重复操作。
• 辅助优化：配置 Maven 镜像源，进一步提升依赖下载速度，彻底解决 Gradle 相关的网络问题。

结尾

通过以上两种方案，你可以根据项目场景灵活选择，彻底告别 Flutter Gradle 下载慢、下载失败的问题。