Flutter SDK 安装与国内镜像配置全流程（Windows / macOS / Linux）-EW帮帮网

这是一份面向国内网络环境的 Flutter 从零到可运行指引：覆盖 SDK 安装、平台依赖准备、国内镜像配置（PUB_HOSTED_URL、FLUTTER_STORAGE_BASE_URL）、Android 侧 Gradle 仓库加速，以及 Java/Gradle 版本兼容的关键坑位与排查思路。文末附常见报错处理与一键回滚镜像的方法，便于论坛读者收藏查阅。

官方文档现已给出 “在中国使用 Flutter” 的镜像配置方法，核心就是设置两枚环境变量：
PUB_HOSTED_URL（Dart/Flutter 包索引镜像）与 FLUTTER_STORAGE_BASE_URL（Flutter 引擎与二进制制品镜像）。本文遵循该做法，并补充国内常用的 Gradle/Maven 加速实践。(Flutter 文档, Flutter 文档)

0. 你要准备什么

一个干净的终端环境（Windows 推荐 PowerShell，macOS/Linux 用系统 shell）。
Android 目标：Android Studio + Android SDK +（可选）JDK17（见 §4 兼容性）。
iOS 目标（仅 macOS）：Xcode + CocoaPods。
Flutter SDK 压缩包，或按官方安装页分平台引导进行（本文不改写官方安装路径，仅补充国内网络要点）。(Flutter 文档)

1. 获取并安装 Flutter SDK

Windows

前往官方安装页选择 Windows，下载 Flutter SDK 压缩包（stable 渠道即可）。
解压到你希望的目录（例如 C:\dev\flutter）。
添加 PATH（PowerShell 推荐做法）：

[Environment]::SetEnvironmentVariable(
  "Path",
  $env:Path + ";C:\dev\flutter\bin",
  "User"
)

新开终端，执行 flutter doctor 进行首次体检。(Flutter 文档)

macOS

从官方安装页下载 macOS 版 SDK，或使用 VS Code 的“Download SDK”引导。
解压到例如 ~/dev/flutter，并写 PATH：

echo 'export PATH="$HOME/dev/flutter/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
flutter doctor

（VS Code 也支持“Locate/Download SDK”向导，初学者友好。) (Flutter 文档)

Linux

下载 Linux 版 SDK 至 ~/dev/flutter。
添加 PATH 并体检：

echo 'export PATH="$HOME/dev/flutter/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
flutter doctor

（安装/体检流程与官方一致。） (Flutter 文档)

2. 国内镜像配置（强烈建议）

在中国大陆网络环境，配置镜像能显著提升 flutter pub get、引擎二进制拉取等步骤的成功率与速度。官方建议为机器设置两枚变量：PUB_HOSTED_URL 与 FLUTTER_STORAGE_BASE_URL。下面给出临时与长期两种方式。(Flutter 文档, Flutter 文档)

2.1 临时生效（当前终端窗口有效）

macOS / Linux：

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

Windows PowerShell：

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

2.2 永久生效（写入用户环境）

macOS / Linux（以 zsh 为例）：

cat <<'EOF' >> ~/.zshrc
export PUB_HOSTED_URL="https://pub.flutter-io.cn"
export FLUTTER_STORAGE_BASE_URL="https://storage.flutter-io.cn"
EOF
source ~/.zshrc

Windows（PowerShell 写入“用户环境变量”）：

[Environment]::SetEnvironmentVariable("PUB_HOSTED_URL","https://pub.flutter-io.cn","User")
[Environment]::SetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL","https://storage.flutter-io.cn","User")

⚠️ 小坑：Windows 不要带引号或多余空格，否则会出现 Invalid PUB_HOSTED_URL 报错；修改后需重启终端/IDE。(Stack Overflow, GitHub)

2.3 验证镜像是否生效

flutter doctor
flutter pub get -v
# 终端输出中应能看到访问 *.flutter-io.cn

（官方中国区文档亦有同样说明与示例。）(Flutter 文档)

3. Android 侧依赖与 Gradle/Maven 加速（可选但推荐）

Flutter 构建 Android 时会下载 Android Gradle Plugin、Google Maven 以及第三方库。国内可通过 阿里云 Maven 做加速镜像（注意：仍建议保留官方 google()/mavenCentral() 以便回退）。示例以 AGP 7/8 的现代结构为例：

3.1 在 `android/settings.gradle` 中添加镜像仓库

pluginManagement {
  repositories {
    maven { url 'https://maven.aliyun.com/repository/gradle-plugin' } // Gradle 插件
    maven { url 'https://maven.aliyun.com/repository/google' }        // Google Maven 镜像
    maven { url 'https://maven.aliyun.com/repository/public' }        // Central 聚合
    gradlePluginPortal()
    google()
    mavenCentral()
  }
}

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
  repositories {
    maven { url 'https://maven.aliyun.com/repository/google' }
    maven { url 'https://maven.aliyun.com/repository/public' }
    google()
    mavenCentral()
  }
}

（以上镜像地址来自阿里云公开镜像；你也可以在本机 ~/.gradle/init.gradle(.kts) 里做全局替换，便于多项目统一配置。）(developer.aliyun.com, GitHub, Stack Overflow)

提醒：不要再使用 jcenter()（已废弃），如见到请移除或替换为 mavenCentral() 与镜像仓库。(Stack Overflow)

3.2 Gradle Wrapper 下载慢怎么办？

出于安全与稳定考虑，不建议修改 gradle-wrapper.properties 的官方分发地址（services.gradle.org）。若下载缓慢，可以在 CI 或局域网侧做缓存代理/镜像，或预热到私有仓（Gradle 官方也建议用缓存/代理来降流量）。(blog.gradle.org)

4. Java / Gradle / Android Studio 版本兼容要点（高频坑）

Android Studio Flamingo 起默认内置 JDK 17；部分旧 Gradle (< 7.3) 无法在 JDK 17 下运行，需将工程 Gradle 升级至 7.3–7.6.1 区间或更高版本。Flutter 官方迁移指引给出了明确路线与命令。(Flutter 文档)
如需固定 Flutter 使用的 JDK（比如统一为 JDK 17 以匹配 AGP 8），可执行：
```
flutter config --jdk-dir=<你的JDK路径>
flutter doctor -v
```
官方文档示例（macOS）路径类似：/opt/homebrew/Cellar/openjdk@17/.../Contents/Home。(Flutter 文档)
查看系统已安装的 Java（macOS）：
```
/usr/libexec/java_home -V
```
在 Android Studio 里也可 取消“Use embedded JDK” 并指向你安装的 JDK 目录（Windows/All 平台通用）。(Stack Overflow)

经验法则：保持 JDK=17 + AGP=8.x + Gradle 8.x 往往最省心；若升级 Android Studio 后编译异常，先跑 flutter doctor -v 看 “正在使用的 Java 版本/路径”，再按官方迁移文档调整 Gradle/AGP。(Flutter 文档)

5. 创建并运行你的第一个 Flutter 应用（含镜像校验）

flutter create hello_flutter
cd hello_flutter

# 再次确认镜像生效（可选）
flutter pub get -v

# Android
flutter run -d emulator-5554

# iOS（仅 macOS，先在 Xcode 中同意许可并安装额外组件）
flutter run -d ios

如果你用 VS Code，新建项目时可“Locate/Download SDK”；安装向导与 Flutter SDK 能自动联动，不影响镜像配置。(Flutter 文档)

6. 进阶：多版本并存（FVM）

团队协作中，不同项目可能依赖不同的 Flutter 版本。推荐用 FVM（Flutter Version Management） 做项目级 SDK 管理：

# macOS（示例）
brew install fvm
cd your_project
fvm use 3.22.0
fvm flutter doctor

FVM 能在每个项目锁定独立的 Flutter 版本，避免全局升级带来的连锁问题。(FVM)

7. 常见问题（FAQ）

Q1：flutter pub get 超时 / 依赖下载慢？
A：确认已设置并生效 PUB_HOSTED_URL 与 FLUTTER_STORAGE_BASE_URL；Windows 下特别注意不要把变量值写成 " https://xxx"（前后多空格或引号）。 (Stack Overflow)

Q2：升级 Android Studio 后编译报 Java/Gradle 兼容错误？
A：flutter doctor -v 看清“正在使用的 Java 版本路径”；按官方迁移指南提升 Gradle 到兼容版本，或用 flutter config --jdk-dir=<JDK17路径> 固定到 JDK 17。(Flutter 文档)

Q3：Gradle 依赖仓库解析缓慢？
A：在 settings.gradle 的 pluginManagement / dependencyResolutionManagement 中添加阿里云镜像（并保留 google() / mavenCentral() 兜底）；或用 ~/.gradle/init.gradle(.kts) 全局替换。(developer.aliyun.com, Stack Overflow)

Q4：还需要改 jcenter() 吗？
A：jcenter() 已废弃，建议移除并用 mavenCentral() / 国内镜像替代。(Stack Overflow)

8. 一键回滚镜像 / 清理缓存

临时取消（当前终端）

macOS / Linux：

unset PUB_HOSTED_URL
unset FLUTTER_STORAGE_BASE_URL

Windows（PowerShell）：

Remove-Item Env:PUB_HOSTED_URL
Remove-Item Env:FLUTTER_STORAGE_BASE_URL

永久移除（Windows 用户环境）

[Environment]::SetEnvironmentVariable("PUB_HOSTED_URL",$null,"User")
[Environment]::SetEnvironmentVariable("FLUTTER_STORAGE_BASE_URL",$null,"User")

清理缓存

flutter clean
# 可选：清理 pub 缓存
rm -rf ~/.pub-cache

9. 速查清单（建议收藏）

SDK 安装与平台准备：按官方安装页分平台指引，先跑 flutter doctor。(Flutter 文档)
中国大陆镜像：
PUB_HOSTED_URL=https://pub.flutter-io.cn
FLUTTER_STORAGE_BASE_URL=https://storage.flutter-io.cn（临时/永久均可）。 (Flutter 文档, Flutter 文档)
Android 依赖加速：在 settings.gradle 配置阿里云镜像 + 保留 google()/mavenCentral()。(developer.aliyun.com)
Java/Gradle 兼容：JDK17 + AGP8 + Gradle8 通常更稳；必要时 flutter config --jdk-dir=<JDK17>。(Flutter 文档)
遇到 Invalid PUB_HOSTED_URL：去掉引号/空格，重启终端或 IDE。(Stack Overflow)

参考与延伸

官方：Using Flutter in China（含各平台设置镜像示例）。(Flutter 文档)
中文站：在中国网络环境下使用 Flutter（附持久化 export 示例）。(Flutter 文档)
官方：Android Java/Gradle 迁移指南（JDK 17 与 Gradle 7.x/8.x 兼容说明）。(Flutter 文档)
Gradle/Maven 国内镜像（阿里云示例与仓库列表）。(developer.aliyun.com, Eitan Liu)
FVM：多版本管理工具（项目级锁定 Flutter 版本）。(FVM)

Flutter SDK 安装与国内镜像配置全流程（Windows / macOS / Linux）

0. 你要准备什么

1. 获取并安装 Flutter SDK

Windows

macOS

Linux

2. 国内镜像配置（强烈建议）

2.1 临时生效（当前终端窗口有效）

2.2 永久生效（写入用户环境）

2.3 验证镜像是否生效

3. Android 侧依赖与 Gradle/Maven 加速（可选但推荐）

3.1 在 `android/settings.gradle` 中添加镜像仓库

3.2 Gradle Wrapper 下载慢怎么办？

4. Java / Gradle / Android Studio 版本兼容要点（高频坑）

5. 创建并运行你的第一个 Flutter 应用（含镜像校验）

6. 进阶：多版本并存（FVM）

7. 常见问题（FAQ）

8. 一键回滚镜像 / 清理缓存

9. 速查清单（建议收藏）

参考与延伸

网站公告

今日签到

热门文章

最新发布

Flutter SDK 安装与国内镜像配置全流程（Windows / macOS / Linux）

0. 你要准备什么

1. 获取并安装 Flutter SDK

Windows

macOS

Linux

2. 国内镜像配置（强烈建议）

2.1 临时生效（当前终端窗口有效）

2.2 永久生效（写入用户环境）

2.3 验证镜像是否生效

3. Android 侧依赖与 Gradle/Maven 加速（可选但推荐）

3.1 在 android/settings.gradle 中添加镜像仓库

3.2 Gradle Wrapper 下载慢怎么办？

4. Java / Gradle / Android Studio 版本兼容要点（高频坑）

5. 创建并运行你的第一个 Flutter 应用（含镜像校验）

6. 进阶：多版本并存（FVM）

7. 常见问题（FAQ）

8. 一键回滚镜像 / 清理缓存

9. 速查清单（建议收藏）

参考与延伸

网站公告

今日签到

热门文章

最新发布

3.1 在 `android/settings.gradle` 中添加镜像仓库