国内网络环境下全栈移动开发环境配置指南：Flutter 与 Android (Kotlin) 镜像加速
对于中国的移动开发者而言，“配环境”往往是项目开始前的第一道拦路虎。无论是使用 Google 推出的跨平台框架 Flutter，还是原生 Android (Kotlin) 开发，其核心依赖（Dart SDK、Android SDK、Gradle 插件、Maven 包）大多托管在 Google 服务器或国际公共仓库上。
在国内网络环境下，直接访问这些资源往往伴随着极高的延迟和频繁的超时错误。本文将手把手教你如何通过配置国内镜像源，让 Flutter 和 Android 的开发环境“飞”起来。
第一部分：Flutter 开发环境镜像配置
Flutter 的加速核心在于两个环境变量：PUB_HOSTED_URL（用于 Dart 包管理）和 FLUTTER_STORAGE_BASE_URL（用于 Flutter 引擎二进制文件下载）。
1. 推荐镜像源
- 上海交通大学 (SJTUG):
- PUB:
https://mirrors.sjtug.sjtu.edu.cn/dart-pub - Storage:
https://mirrors.sjtug.sjtu.edu.cn/flutter - 清华大学 (TUNA):
- PUB:
https://mirrors.tuna.tsinghua.edu.cn/dart-pub - Storage:
https://mirrors.tuna.tsinghua.edu.cn/flutter
2. 配置步骤
🪟 Windows 系统
永久生效配置：
- 右键“此电脑” -> 属性 -> 高级系统设置 -> 环境变量。
- 在“用户变量”中新建以下两项：
- 变量名：
PUB_HOSTED_URL，变量值：https://mirrors.sjtug.sjtu.edu.cn/dart-pub - 变量名：
FLUTTER_STORAGE_BASE_URL，变量值：https://mirrors.sjtug.sjtu.edu.cn/flutter - 点击确定保存，并重启终端或 IDE。
🍎 macOS / 🐧 Linux 系统
编辑 Shell 配置文件（~/.zshrc 或 ~/.bash_profile）：
export PUB_HOSTED_URL=https://mirrors.sjtug.sjtu.edu.cn/dart-pub
export FLUTTER_STORAGE_BASE_URL=https://mirrors.sjtug.sjtu.edu.cn/flutter保存后执行 source ~/.zshrc (或对应文件) 使配置生效。
3. 验证
运行 flutter doctor -v 或 flutter pub get。如果日志中显示从 mirrors.sjtug.sjtu.edu.cn 下载资源且速度飞快，则配置成功。
第二部分：Android (Kotlin) 开发环境镜像配置
Android 项目的构建依赖于 Gradle，加速的核心是将 google()、mavenCentral() 以及 Gradle Wrapper 的下载地址替换为国内镜像。阿里云镜像在此场景下表现最为稳定。
1. 推荐镜像源 (阿里云)
- 公共仓库:
https://maven.aliyun.com/repository/public - Google 仓库:
https://maven.aliyun.com/repository/google - Gradle 插件仓库:
https://maven.aliyun.com/repository/gradle-plugin
2. 配置方案一：项目级配置（推荐团队使用）
修改项目根目录下的 settings.gradle.kts (Kotlin DSL) 或 settings.gradle (Groovy)。
Kotlin DSL (settings.gradle.kts) 示例：
pluginManagement {
repositories {
maven("https://maven.aliyun.com/repository/gradle-plugin") // 优先插件镜像
google()
mavenCentral()
gradlePluginPortal()
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
maven("https://maven.aliyun.com/repository/public") // 优先公共镜像
maven("https://maven.aliyun.com/repository/google") // 优先 Google 镜像
google()
mavenCentral()
}
}注意：将阿里云仓库置于 google() 和 mavenCentral() 之前，确保优先命中国内源。
3. 配置方案二：加速 Gradle 本身下载
修改 gradle/wrapper/gradle-wrapper.properties，替换 distributionUrl。
修改前：
distributionUrl=https\://services.gradle.org/distributions/gradle-8.7-bin.zip修改后 (使用腾讯或阿里镜像)：
# 方案 A: 腾讯镜像
distributionUrl=https\://mirrors.cloud.tencent.com/gradle/gradle-8.7-bin.zip
# 方案 B: 阿里镜像 (有时需特定路径，若失效请用方案 A)
# distributionUrl=https\://mirrors.aliyun.com/macros/gradle/gradle-8.7-bin.zip4. 配置方案三：全局配置 (可选)
若不想修改每个项目，可在用户目录 ~/.gradle/ (Mac/Linux) 或 C:\Users\<用户名>\.gradle\ (Windows) 下创建 init.gradle 文件，注入阿里云仓库配置。这会对本机所有 Gradle 项目生效。
5. 验证
在终端执行 ./gradlew clean build --refresh-dependencies。观察控制台日志，确认依赖是从 maven.aliyun.com 下载的，且无超时错误。
常见问题排查 (FAQ)
- 配置后不生效？
- Flutter: 务必完全重启终端或 IDE，环境变量仅在进程启动时加载。
- Android: 尝试删除
.gradle缓存目录 (~/.gradle/caches) 后重新构建，强制刷新依赖。 - 依然超时怎么办？
- 尝试切换镜像源（如从阿里切换到清华，或从交大切换到腾讯）。
- 检查公司内网防火墙是否拦截了特定的域名。
- JCenter 还能用吗？
- 不能。JCenter 已正式停止服务，请将所有
jcenter()替换为mavenCentral()并配合阿里云镜像使用。 - Git 克隆慢？
- Flutter 源码克隆可暂时使用 Gitee 镜像，但日常开发建议配置好上述环境变量后直接使用官方源，以保证版本最新。
工欲善其事，必先利其器。通过简单的镜像配置，我们可以将原本需要数小时的环境搭建过程缩短至几分钟，让开发者将宝贵的时间集中在代码逻辑与产品创新上。
