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

一、问题背景在创建或运行 Flutter 项目时经常会遇到 Gradle 下载缓慢、超时或失败的问题这是因为默认的 Gradle 分发地址位于国外国内网络环境下访问不稳定。本文将从临时修改当前项目和永久修改 Flutter 模板两个维度提供完整解决方案。二、临时方案修改当前项目的 Gradle 分发地址适用于已有项目快速解决当前构建问题。1. 使用国内镜像源推荐找到项目中的android/gradle/wrapper/gradle-wrapper.properties文件将distributionUrl替换为国内镜像地址如腾讯云、阿里云# 原地址注释掉 # distributionUrlhttps\://services.gradle.org/distributions/gradle-8.12-all.zip # 替换为腾讯云镜像 distributionUrlhttps://mirrors.cloud.tencent.com/gradle/gradle-8.12-all.zip2. 检查 Gradle 版本一致性确保distributionUrl中的 Gradle 版本与项目要求一致可在android/build.gradle中查看所需版本dependencies { classpath com.android.tools.build:gradle:7.3.0 }若版本不匹配需下载对应版本的 Gradle 包并更新distributionUrl。3. 本地配置 Gradle离线可用若网络问题无法解决可手动下载 Gradle 压缩包配置为本地路径distributionUrlfile:///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.tmpl2. 编辑模板文件打开文件注释掉原有的distributionUrl替换为国内镜像地址distributionBaseGRADLE_USER_HOME distributionPathwrapper/dists zipStoreBaseGRADLE_USER_HOME zipStorePathwrapper/dists ## 注释掉官方默认地址 ## distributionUrlhttps\://services.gradle.org/distributions/gradle-{{gradleVersion}}-all.zip ## 更改为国内镜像分发地址保留变量 {{gradleVersion}} 以适配版本 distributionUrlhttps\://mirrors.cloud.tencent.com/gradle/gradle-{{gradleVersion}}-all.zip3. 生效验证保存文件后重新创建 Flutter 项目新项目的android/gradle/wrapper/gradle-wrapper.properties会自动使用国内镜像地址无需再次手动修改。四、常见问题排查版本不匹配报错确保distributionUrl中的 Gradle 版本与android/build.gradle中com.android.tools.build:gradle版本兼容。镜像地址失效若腾讯云镜像不可用可替换为阿里云镜像propertiesdistributionUrlhttps://maven.aliyun.com/repository/gradle-distributions/gradle-{{gradleVersion}}-all.zip离线模式若完全无网络可使用本地路径配置提前下载好对应版本的 Gradle 压缩包。五、总结临时修复针对已有项目直接修改gradle-wrapper.properties快速解决当前构建问题。永久生效修改 Flutter SDK 模板文件新建项目自动使用国内镜像避免重复操作。辅助优化配置 Maven 镜像源进一步提升依赖下载速度彻底解决 Gradle 相关的网络问题。结尾通过以上两种方案你可以根据项目场景灵活选择彻底告别 Flutter Gradle 下载慢、下载失败的问题。