Skip to content

Dart & Flutter 镜像加速配置

核心镜像变量配置

Dart和Flutter依赖两个关键环境变量实现加速,所有操作系统均需配置以下内容(任选一个镜像站):

推荐镜像源列表

  1. Flutter社区镜像(官方维护,稳定性优先)

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

  2. 清华大学 TUNA 镜像(同步频率高,支持多协议)

    PUB_HOSTED_URL=https://mirrors.tuna.tsinghua.edu.cn/dart-pub
    FLUTTER_STORAGE_BASE_URL=https://mirrors.tuna.tsinghua.edu.cn/flutter
    

  3. 上海交大 SJTUG 镜像(实时同步,回源策略完善)

    PUB_HOSTED_URL=https://dart-pub.mirrors.sjtug.sjtu.edu.cn
    FLUTTER_STORAGE_BASE_URL=https://mirrors.sjtug.sjtu.edu.cn
    

  4. 腾讯云镜像(适合使用腾讯云服务的用户)

    PUB_HOSTED_URL=https://mirrors.cloud.tencent.com/dart-pub
    FLUTTER_STORAGE_BASE_URL=https://mirrors.cloud.tencent.com/flutter
    

操作系统配置步骤

Windows 系统

  1. 临时生效(当前会话窗口)

打开PowerShell或CMD:

$env:PUB_HOSTED_URL="镜像地址"
$env:FLUTTER_STORAGE_BASE_URL="镜像地址"
  1. 永久生效 [Environment]::SetEnvironmentVariable("PUB_HOSTED_URL", "镜像地址", "Machine") [Environment]::SetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL", "镜像地址", "Machine")

macOS / Linux 系统

  1. 临时生效(当前会话窗口)

    export PUB_HOSTED_URL="镜像地址"
    export FLUTTER_STORAGE_BASE_URL="镜像地址"
    

  2. 永久生效

  3. 编辑Shell配置文件(如 ~/.bashrc~/.zshrc):
    echo 'export PUB_HOSTED_URL="镜像地址"' >> ~/.bashrc
    echo 'export FLUTTER_STORAGE_BASE_URL="镜像地址"' >> ~/.bashrc
    
  4. 生效配置:source ~/.bashrc

Flutter SDK 下载加速

若需手动下载SDK,将原始URL中的 storage.googleapis.com 替换为镜像域名。例如:

  • 原始URL

    https://storage.googleapis.com/flutter_infra_release/releases/stable/windows/flutter_windows_v3.13.0-stable.zip
    

  • 镜像URL(以Flutter社区为例):

https://storage.flutter-io.cn/flutter_infra_release/releases/stable/windows/flutter_windows_v3.13.0-stable.zip

Android Studio 相关配置

  1. Gradle镜像加速

在项目根目录的 build.gradle 中添加阿里云仓库:

buildscript {
  repositories {
    maven { url 'https://maven.aliyun.com/repository/google' }
    maven { url 'https://maven.aliyun.com/repository/central' }
  }
}
  1. Android SDK镜像

  2. 打开 Android Studio → Settings → Android SDK → SDK Update Sites

  3. 添加镜像源(如清华源):
    https://mirrors.tuna.tsinghua.edu.cn/android/repository/
    

验证配置

  1. 执行 flutter doctor,检查依赖下载是否正常。
  2. 运行 echo $PUB_HOSTED_URL(Unix)或 echo %PUB_HOSTED_URL%(Windows),确认变量已生效。

注意事项

  1. 发布Package时需要恢复默认源

发布到 pub.dev 前需取消镜像变量,否则会失败:

unset PUB_HOSTED_URL  # Unix
Remove-Item Env:\PUB_HOSTED_URL  # PowerShell
  1. 镜像同步延迟:若遇到依赖版本不一致问题,尝试切换其他镜像源。

常见问题

  • 镜像失效:检查镜像站状态页面(如清华镜像状态页),或切换备用镜像。
  • 环境变量不生效:确保变量名无拼写错误,重启终端或IDE。
  • 混合开发配置:若集成到Android原生项目,需同步配置Gradle镜像。

通过以上配置,可显著提升Dart包下载和Flutter SDK安装速度。更多细节可参考Flutter中文文档