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

这是一份面向国内网络环境的 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

  1. 前往官方安装页选择 Windows，下载 Flutter SDK 压缩包（stable 渠道即可）。

  2. 解压到你希望的目录（例如 C:\dev\flutter）。

  3. 添加 PATH（PowerShell 推荐做法）：

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

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

macOS

  1. 从官方安装页下载 macOS 版 SDK，或使用 VS Code 的“Download SDK”引导。

  2. 解压到例如 ~/dev/flutter，并写 PATH：

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

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

Linux

  1. 下载 Linux 版 SDK 至 ~/dev/flutter。

  2. 添加 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)

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如若转载，请注明出处：http://www.pswp.cn/news/921955.shtml
繁体地址，请注明出处：http://hk.pswp.cn/news/921955.shtml

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

【Java】NIO 简单介绍

【Java】NIO 简单介绍

简介 从 Java 1.4 版本开始引入的一个新的 I/O API&#xff0c;可以替代标准的 Java I/O。提供了与标准 I/O 不同的工作方式&#xff0c;核心是 通道&#xff08;Channel&#xff09;、缓冲区&#xff08;Buffer&#xff09; 和 选择器&#xff08;Selector&#xff09;。支持非…
阅读更多...
Java爬虫获取京东item_get_app数据的实战指南

Java爬虫获取京东item_get_app数据的实战指南

一、引言京东开放平台提供了丰富的API接口&#xff0c;其中item_get_app接口可用于获取商品的详细信息。这些数据对于市场分析、价格监控、商品推荐等场景具有重要价值。本文将详细介绍如何使用Java编写爬虫&#xff0c;通过调用京东开放平台的item_get_app接口获取商品详情数据…
阅读更多...
Vue3源码reactivity响应式篇之批量更新

Vue3源码reactivity响应式篇之批量更新

概述 在vue3响应式系统设计中&#xff0c;批量更新是优化性能的核心机制之一。当短时间内频繁多次修改响应式数据时&#xff0c;批量更新可以避免频繁触发订阅者的更新操作&#xff0c;将这些更新操作合并为一次&#xff0c;从而减少不必要的计算和DOM操作。 批量更新也是利用链…
阅读更多...
AI 模型训练过程中参数用BF16转向FP16的原因

AI 模型训练过程中参数用BF16转向FP16的原因

大模型训练从 FP16 转向 BF16 是一个关键的技术演进&#xff0c;其核心原因在于 BF16 在动态范围和精度之间取得了更优的平衡&#xff0c;从而极大地提升了训练&#xff08;尤其是大模型训练&#xff09;的稳定性和有效性。 1. 背景 为什么需要半精度浮点数 (FP16)&#xff1f;…
阅读更多...
python网络爬取个人学习指南-（五）

python网络爬取个人学习指南-（五）

**************************************************************************************************************author&#xff1a;keyinfodate&#xff1a;2025-09-09 23:50title&#xff1a;网络信息爬取之多联级标题内容点击****************************************…
阅读更多...
RAG - 检索增强生成

RAG - 检索增强生成

第一部分&#xff1a;RAG 详解一、RAG 是什么&#xff1f;RAG&#xff08;Retrieval-Augmented Generation&#xff0c;检索增强生成&#xff09;是一种将信息检索&#xff08;或知识检索&#xff09;与大语言模型&#xff08;LLM&#xff09;的生成能力相结合的技术框架。它的…
阅读更多...
大数据毕业设计选题推荐-基于大数据的分化型甲状腺癌复发数据可视化分析系统-Spark-Hadoop-Bigdata

大数据毕业设计选题推荐-基于大数据的分化型甲状腺癌复发数据可视化分析系统-Spark-Hadoop-Bigdata

✨作者主页&#xff1a;IT研究室✨ 个人简介&#xff1a;曾从事计算机专业培训教学&#xff0c;擅长Java、Python、微信小程序、Golang、安卓Android等项目实战。接项目定制开发、代码讲解、答辩教学、文档编写、降重等。 ☑文末获取源码☑ 精彩专栏推荐⬇⬇⬇ Java项目 Python…
阅读更多...
Spring Bean扫描

Spring Bean扫描

好的&#xff0c;没有问题。基于我们之前讨论的内容&#xff0c;这是一篇关于 Spring Bean 扫描问题的深度解析博客。Spring Bean扫描作者&#xff1a;Gz | 发布时间&#xff1a;2025年9月9日&#x1f3af; Spring如何找到你的Bean&#xff1f; 首先要理解原理。Spring的组件扫…
阅读更多...
【 运维相关】-- HTTP 压测/负载发生器之新秀 oha

【 运维相关】-- HTTP 压测/负载发生器之新秀 oha

目录 oha 项目分析&#xff08;hatoo/oha&#xff09; 一、概述 二、安装 三、快速上手 三、常用参数&#xff08;摘选&#xff09; 四、输出解读&#xff08;终端 TUI&#xff09; 五、与其它工具对比 六、最佳实践 七、注意事项 八、参考 oha 项目分析&#xff08;h…
阅读更多...
淘宝闪购基于FlinkPaimon的Lakehouse生产实践：从实时数仓到湖仓一体化的演进之路

淘宝闪购基于FlinkPaimon的Lakehouse生产实践：从实时数仓到湖仓一体化的演进之路

摘要&#xff1a;本文整理自淘宝闪购(饿了么)大数据架构师王沛斌老师在 Flink Forward Asia 2025 城市巡回上海站的分享。引言在数字化转型的浪潮中&#xff0c;企业对实时数据处理的需求日益增长。传统的实时数仓架构在面对业务快速变化和数据规模爆炸性增长时&#xff0c;逐渐…
阅读更多...
Android应用添加日历提醒功能

Android应用添加日历提醒功能

功能 在安卓应用里调用系统日历&#xff0c;直接创建一个带提醒的日历事件&#xff0c;甚至不需要跳转到日历界面&#xff0c;只需要获取系统日历的读取权限即可。 需要的权限 在AndroidManifest.xml里添加 <uses-permission android:name"android.permission.READ_CAL…
阅读更多...
‌Git Bisect 二分查找定位错误总结

‌Git Bisect 二分查找定位错误总结

# Git Bisect 二分查找指南## 1. 基本原理&#xff08;ASCII示意图&#xff09; 假设提交历史是一条时间线&#xff0c;Ggood&#xff08;正常&#xff09;&#xff0c;Bbad&#xff08;异常&#xff09;&#xff1a;提交顺序: G --- G --- G --- B --- B --- B | | | 初始正常…
阅读更多...
ThingsKit物联网平台 v2.0.0 发布｜前端UI重构、底层架构升级

ThingsKit物联网平台 v2.0.0 发布｜前端UI重构、底层架构升级

v2.0.0 Release发布日期&#xff1a;2025/08/25 代码标签&#xff1a;v2.0.0_Release&#x1f947; 新增功能国标级联&#xff08;支持上级、下级国标级联&#xff09;视频回放、录像计划&#xff08;用户可以通过录像计划生成对应的视频回放并查看&#xff09;Modbus_TCP协…
阅读更多...
Lua ＞ Mac Mini M4安装openresty

Lua ＞ Mac Mini M4安装openresty

Mac Mini M4安装openresty 主要参考 https://www.cnblogs.com/helios-fz/p/15703260.html brew uninstall nginxbrew update brew install pcre openssl #brew install geoip# brew tap openresty/brew # brew install openresty # brew install openresty/brew/openresty# VER…
阅读更多...
【多线程案例】：单例模式

【多线程案例】：单例模式

多线程案例8.1 单例模式饿汉模式懒汉模式懒汉模式-单线程版懒汉模式-多线程版懒汉模式-多线程版(改进)8.1 单例模式 单个实例. 在一个 java 进程中, 要求指定的类,只能有唯–个实例。&#xff08;尝试 new 多个实例的时候, 就会直接编译报错&#xff09; 单例模式是校招中最常…
阅读更多...
【Python/Pytorch】-- 贝叶斯定理

【Python/Pytorch】-- 贝叶斯定理

文章目录 文章目录01 贝叶斯定理的理解02 在MRI重建领域应用01 贝叶斯定理的理解 贝叶斯定理的基本公式&#xff1a;P(A|B)P(B|A)*P(A) / P(B) 首先是如何理解这个公式&#xff1f; 在B事件发生的条件下&#xff0c;A发生的概率 P(A|B) 在B事件发生的条件下&#xff0c;A和B同…
阅读更多...
子网掩码的隐形陷阱：为何能ping通却无法HTTPS访问

子网掩码的隐形陷阱：为何能ping通却无法HTTPS访问

问题现象深度解析在近期企业网络维护中&#xff0c;运维团队发现一个具有教学意义的典型案例&#xff1a;某台部署在10.165.111.0/24网段的业务服务器&#xff08;10.165.111.71&#xff09;可以成功ping通目标中间件主机(10.165.110.11)&#xff0c;但通过HTTPS协议访问https:…
阅读更多...
【ArcGIS】如何编辑图层的属性表

【ArcGIS】如何编辑图层的属性表

GIS按属性选择后删除所选项呈现灰色_arcgis删除字段灰色-CSDN博客
阅读更多...
大数据各组件flume，datax，presto，DolphinScheduler，findBI在大数据数仓架构中的作用和功能。

大数据各组件flume，datax，presto，DolphinScheduler，findBI在大数据数仓架构中的作用和功能。

一、数据仓库核心价值铺垫在讲具体技术前&#xff0c;先明确数据仓库&#xff08;Data Warehouse&#xff0c;简称数仓&#xff09; 的核心作用&#xff1a; 数据仓库是 “整合企业多源数据、按业务主题组织、支持决策分析” 的结构化数据存储体系&#xff0c;核心价值是打破数…
阅读更多...
React From表单使用Formik和yup进行校验

React From表单使用Formik和yup进行校验

一、Formik的使用 官方文档地址&#xff1a;https://formik.org/docs/tutorial#validation 首先安装依赖 yarn add formik2.导入并初始化 import { useFormik } from formik; initialValues&#xff1a;初始化 输入框的密码和账号 onSubmit&#xff1a;当点击提交按钮时&am…
阅读更多...
最新文章

Copyright @ 2022~2023