解决 Flutter 项目 Gradle 依赖下载失败问题

本文最后更新于：2026年3月16日 上午

问题描述

在 Flutter Android 项目构建时，经常会遇到 Gradle 依赖包下载失败的问题，报错信息通常为：

  • Connection timed out
  • Could not resolve xxx.xxx.xxx
  • Read timed out

这是由于网络问题导致无法访问 Google Maven、JCenter 等国外仓库，需要配置国内镜像源来解决。

解决方案一：修改 Gradle 源地址（推荐）

1. 修改项目级 build.gradle

找到 Flutter 项目中的 android/build.gradle 文件，在 repositories 配置中替换为国内镜像源。

该文件中通常有两处需要修改：

  • buildscript 块中的 repositories
  • allprojects 块中的 repositories

修改后的完整示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
buildscript {
    repositories {
        // 阿里云公共仓库
        maven { url 'https://maven.aliyun.com/repository/public' }
        // 阿里云 Google 仓库
        maven { url 'https://maven.aliyun.com/repository/google' }
        // 阿里云 JCenter 仓库
        maven { url 'https://maven.aliyun.com/repository/jcenter' }
        // 阿里云 Gradle Plugin 仓库
        maven { url 'https://maven.aliyun.com/repository/gradle-plugin' }
        
        mavenCentral()
        google()
    }

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

allprojects {
    repositories {
        // 阿里云公共仓库
        maven { url 'https://maven.aliyun.com/repository/public' }
        // 阿里云 Google 仓库
        maven { url 'https://maven.aliyun.com/repository/google' }
        // 阿里云 JCenter 仓库
        maven { url 'https://maven.aliyun.com/repository/jcenter' }
        
        mavenCentral()
        google()
    }
}

2. 配置 Gradle Wrapper 镜像（可选）

如果 Gradle 本身下载失败，可以修改 android/gradle/wrapper/gradle-wrapper.properties，使用阿里云镜像：

1
distributionUrl=https\://services.gradle.org/distributions/gradle-x.x-all.zip

改为：

1
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-x.x-all.zip

或使用阿里云：

1
distributionUrl=https\://mirrors.aliyun.com/macports/distfiles/gradle/gradle-x.x-all.zip

3. 重新构建

配置完成后，执行清理并重新构建：

1
2
3
4
5
6
7
cd android
./gradlew clean
./gradlew build
# 或直接在 Flutter 项目根目录
flutter clean
flutter pub get
flutter build apk

解决方案二：手动下载依赖包

如果修改源地址后仍然无法下载某些特定的依赖包，可以采用手动下载的方式。

1. 找到依赖信息

在构建错误日志中找到无法下载的依赖信息，例如：

1
Could not resolve com.example:library:1.0.0

记录下：

  • Group ID: com.example
  • Artifact ID: library
  • Version: 1.0.0

2. 手动下载 JAR/AAR 文件

从以下镜像站或官方仓库下载对应的文件：

构造下载路径（以上例为例）：

1
https://repo1.maven.org/maven2/com/example/library/1.0.0/library-1.0.0.jar

3. 放入 Gradle 缓存目录

将下载的文件放入 Gradle 本地缓存目录：

Windows 路径：

1
C:\Users\{你的用户名}\.gradle\caches\modules-2\files-2.1\{group}\{artifact}\{version}\{hash}\

完整示例：

1
C:\Users\kele\.gradle\caches\modules-2\files-2.1\com.example\library\1.0.0\abc123(随机hash)\library-1.0.0.jar

注意事项：

  • hash 值是随机生成的，可以创建一个随机字符串文件夹
  • 确保文件名格式正确：{artifact}-{version}.jar 或 .aar
  • 需要同时放置 .pom 文件（如果有的话）

4. 重新构建

放置文件后，重新执行构建命令：

1
2
3
4
flutter clean
flutter pub get
cd android
./gradlew build --refresh-dependencies

附加建议

建议使用 Flutter 稳定版

建议使用 Flutter 稳定版（Stable Channel），避免因版本不稳定导致的依赖问题：

1
2
3
4
5
6
# 查看当前通道
flutter channel

# 切换到稳定版
flutter channel stable
flutter upgrade
Flutter
#Flutter
解决 Flutter 项目 Gradle 依赖下载失败问题
http://bestkele.com/2019/11/13/flutter/flutter-dependent/
作者
kele
发布于
2019年11月13日
许可协议