解决 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 下载慢、下载失败的问题。