Flutter 完美切换国内镜像源（终极稳定方案，解决所有下载404/超时/引擎缺失）

一、前言（必看，解决你所有报错根源）

1. 清华 Flutter 镜像已不再推荐：同步滞后、引擎包经常404、新版本缺失，你的报错全部源于此。

2. 目前国内 最稳定、官方认可、同步最全 的镜像：Flutter 社区官方镜像（flutter-io.cn）

3. 切换后可解决：

• flutter upgrade 404 下载失败
• flutter run 引擎 jar 包找不到
• Gradle 编译缺失 debug 引擎文件
• pub get 超时、下载失败
• Dart SDK 下载失败、重试报错

二、核心镜像地址（永久固定）

只使用这两组，放弃所有清华源

Flutter 存储源（引擎/SDK/资源）：https://storage.flutter-io.cn

Pub 包管理源（第三方依赖）：https://pub.flutter-io.cn

三、Windows 系统配置教程（你的系统）

步骤1：删除旧的错误镜像（关键！）

很多人报错是因为残留清华镜像，先彻底清空。

打开 系统属性 → 高级 → 环境变量

在「用户变量」和「系统变量」中，删除以下变量（如果存在）：

• FLUTTER_STORAGE_BASE_URL
• PUB_HOSTED_URL

步骤2：配置稳定国内源

新建两个 用户环境变量：

变量1：

变量名：FLUTTER_STORAGE_BASE_URL

变量值：https://storage.flutter-io.cn

变量2：

变量名：PUB_HOSTED_URL

变量值：https://pub.flutter-io.cn

步骤3：重启终端生效

关闭所有 PowerShell、CMD、VS Code 终端，重新打开。

四、临时切换/还原官方源命令（应急必备）

1. 临时切回【官方源】（用于升级 Flutter 解决404）

每次升级前执行，避免镜像同步问题：

$env:PUB_HOSTED_URL=""
$env:FLUTTER_STORAGE_BASE_URL=""
flutter upgrade

2. 临时切回【国内源】（日常开发用）

$env:PUB_HOSTED_URL="https://pub.flutter-io.cn"
$env:FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"

五、Android Gradle 镜像修复（解决你 jar 包缺失报错）

这是你当前 checkDebugDuplicateClasses 报错 的终极修复，必须配置。

打开项目 android/build.gradle

找到allprojects > repositories，替换为以下内容：

allprojects {
    repositories {
        // 优先本地缓存，彻底解决引擎jar找不到
        maven { url "${System.env.FLUTTER_SDK}/bin/cache/artifacts/engine/android" }
        // 官方国内镜像（稳定）
        maven { url 'https://storage.flutter-io.cn/download.flutter.io' }
        google()
        mavenCentral()
    }
}

六、验证镜像是否配置成功

终端执行：

flutter doctor -v

看到如下字段即成功：

Flutter assets will be downloaded from https://storage.flutter-io.cn

七、全套修复收尾命令（配置完必执行）

进入你的项目目录，执行全套清理修复：

flutter clean
flutter pub cache clean
flutter pub get
flutter run

八、避坑总结（重点）

• 禁止再使用清华 Flutter 镜像：同步不全、新版本必404
• 升级 Flutter 优先切官方源，日常开发用国内源
• Gradle 必须配置 Flutter 国内 Maven 地址，否则编译必报错
• 环境变量修改后必须重启终端，否则不生效

九、Mac/Linux 快速配置（附赠）

编辑 ~/.bashrc 或 ~/.zshrc：

export PUB_HOSTED_URL=https://pub.flutter-io.cn
export FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn