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
英文地址，請注明出處：http://en.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