簡介Flutter 3.0.4穩(wěn)定版Windows安裝包是面向Windows開發(fā)者的跨平臺應(yīng)用開發(fā)工具適合希望用單一代碼庫構(gòu)建Android和iOS應(yīng)用的中初級開發(fā)者。壓縮包內(nèi)集成了完整SDK組件包括dart-sdk運(yùn)行環(huán)境、開發(fā)工具集合、框架依賴包以及各類平臺配置文件解壓配置后即可通過flutter doctor檢查環(huán)境、使用flutter create創(chuàng)建項(xiàng)目并運(yùn)行到模擬器或真機(jī)。整個壓縮包共18337個文件以dart源碼、PNG圖標(biāo)資源、Markdown文檔、JSON配置和YAML工程文件為主還包含Java、Kotlin、Swift等原生平臺文件總體積約894.78MB目錄結(jié)構(gòu)清晰便于按需檢索。已有699人學(xué)習(xí)下載。該穩(wěn)定版本經(jīng)嚴(yán)格測試性能與兼容性可靠內(nèi)置熱重載與豐富widget組件能顯著縮短迭代周期是搭建Flutter開發(fā)環(huán)境、統(tǒng)一團(tuán)隊(duì)SDK版本的高質(zhì)量選擇。1. Flutter Windows 安裝包3.0.4 stable 的離線救場很多人一聽到 Flutter Windows 安裝包第一反應(yīng)是去官網(wǎng)拉最新版裝上?？梢坏┙邮忠粋€ 2022 年前后的老項(xiàng)目這套環(huán)境就卡在版本線上了Flutter SDK 一升級依賴插件紛紛罷工編譯報錯像抽掉了榫卯的木結(jié)構(gòu)你根本分不清是代碼問題還是工具鏈問題。flutter_windows_3.0.4-stable.zip 這份安裝包就是用來鎖定版本救場用的。上個月某開發(fā)者在 Windows 構(gòu)建機(jī)上重新搭 Flutter 環(huán)境要求非常明確不追新只要穩(wěn)定在 3.0.4 stable 上持續(xù)產(chǎn)出 Windows 桌面安裝包。起初都以為 zip 解壓就能用結(jié)果前后折騰三個多小時把 Git、Visual Studio 工具鏈、Android SDK 路徑一排下來才把 flutter run 跑通。這篇就照當(dāng)時的操作順序復(fù)現(xiàn)一遍從解壓、配環(huán)境到最終驗(yàn)證整條鏈路給同樣握著這份 zip、想在 Windows 上固定用 Flutter 3.0.4 的人一條能照著走的路徑。2. 安裝前環(huán)境摸底Flutter 3.0.4 在 Windows 上到底依賴什么2.1 先明確版本定位為什么卡在 3.0.4Flutter 3.0.4 是 3.x 主版本里較早的 stable 補(bǔ)丁版不是滾動更新版的過渡產(chǎn)物。它對應(yīng)的 Dart 語言已經(jīng)全面切換到 null safetypub 生態(tài)里大部分 3.x 插件都能按約束正常解析。選這份 zip 的人多數(shù)不是為了嘗鮮而是要固定一套構(gòu)建環(huán)境。某跨平臺系統(tǒng)的維護(hù)團(tuán)隊(duì)當(dāng)時的情況就是這樣pubspec.lock 里一批插件還停留在早期支持窗口升級 Flutter 就得連帶升級插件成本擋不住于是退回 3.0.4 做回歸構(gòu)建。這個版本的特點(diǎn)是補(bǔ)丁點(diǎn)收斂對 Windows 桌面構(gòu)建的支持已經(jīng)穩(wěn)定比 2.x 時代那些“能跑但到處響警報”的狀態(tài)靠譜得多。我拿到任何一份 Flutter Windows 安裝包都會先回答三個問題再動手。一是這臺機(jī)器之前裝沒裝過其他 Flutter 版本PATH 里有沒有殘留路徑二是項(xiàng)目只要 Windows 桌面輸出還是要兼顧 Android 和 Web三是網(wǎng)絡(luò)環(huán)境能不能直連官方倉庫不能的話鏡像地址要提前備好。這三個問題決定了要不要裝 Android Studio、要不要配鏡像、最終用哪組命令驗(yàn)收。不少人在解壓后才開始想這些裝到一半發(fā)現(xiàn)缺組件環(huán)境被改得亂七八糟。2.2 依賴清單四類不能省的外部工具Flutter 的 Windows 壓縮包本身只是 SDK 主體真正決定能不能跑通的是這一層外圍工具鏈。按 3.0.4 在 Windows 上的實(shí)際需求依賴歸成四類Git、Visual Studio C 工具鏈、Android SDK按需、Chrome按需。組件作用是否必需Git for Windowsflutter.bat 啟動時用 git 獲取版本信息pub 拉取部分依賴也要經(jīng) git必需Visual Studio 或 Build Tools勾選“使用 C 的桌面開發(fā)”提供 MSVC 編譯器、CMake 與 Windows SDK構(gòu)建 Windows 桌面的底層工具鏈必需Android SDK / Android Studio構(gòu)建 Android APKflutter doctor 會檢查此項(xiàng)按需Chrome 瀏覽器Web 調(diào)試模式默認(rèn)啟動的瀏覽器按需第一個坑通常落在 Git 上。有人覺得 Flutter 是離線 zip不需要 Git于是解壓完直接敲 flutter結(jié)果報出 “Unable to locate git”。flutter.bat 的啟動邏輯依賴 git 來拼版本信息哪怕你完全不從 git 拉 Flutter 源碼Git 也不能少。Visual Studio 那個坑更大它不問裝沒裝而是看“使用 C 的桌面開發(fā)”這個工作負(fù)載有沒有勾選。只裝 VS 不勾負(fù)載flutter doctor 照樣報紅桌面構(gòu)建會在 CMake 階段直接中止。Android SDK 和 Chrome 屬于“按需”。只做 Windows 桌面輸出時Android 檢查項(xiàng)可以容忍它飄紅用flutter config --no-enable-android關(guān)掉即可做 Web 調(diào)試時 Chrome 才會成為硬性依賴。我建議先弄清項(xiàng)目目標(biāo)再決定裝哪些不要一上來把全套工具鏈都鋪上后面維護(hù)成本全是自己扛。2.3 目錄規(guī)劃別把 SDK 放進(jìn) Program FilesWindows 裝 Flutter 的第一步不是解壓是選目錄。我踩過幾次坑之后統(tǒng)一了做法SDK 放 D 盤短路徑例如D:\dev\flutter工程目錄放D:\work。不要裝進(jìn)C:\Program Files這目錄帶空格還有權(quán)限管控CMake 拼接路徑時很容易把引號弄錯也不要把 SDK 埋進(jìn)個人目錄的深層路徑。路徑里一旦出現(xiàn)中文或空格報錯往往指向文件缺失繞一大圈才能發(fā)現(xiàn)是路徑字符的事兒。磁盤空間按兩倍余量估算。SDK 解壓后大約 1GB 多bin\cache如果不是預(yù)置完整緩存首次運(yùn)行還會觸發(fā)引擎構(gòu)件下載項(xiàng)目構(gòu)建時臨時文件再加 1GB 左右。動手前我先看一眼目標(biāo)分區(qū)剩余空間C 盤只剩幾個 GB 的機(jī)器就直接把 SDK 放 D 盤省得構(gòu)建到一半磁盤寫滿。# 查看 D 盤剩余空間避免解壓到一半空間不足 Get-PSDrive D | Select-Object Used,Free這條命令只做一件事確認(rèn)目標(biāo)分區(qū)還剩多少空間。Flutter 解壓失敗或構(gòu)建緩存寫不進(jìn)去經(jīng)常不是報錯信息里那個文件有問題而是磁盤滿了寫不進(jìn)臨時目錄。選好目錄后面所有步驟才談得上可復(fù)現(xiàn)。3. 解壓 flutter_windows_3.0.4-stable.zip這一步最容易栽跟頭3.1 三種解壓方式與我的推薦拿到 zip 后解壓看似人人都會實(shí)際翻車率不低。資源管理器右鍵“全部解壓”最直觀但大文件解壓時看不到進(jìn)度文件被占用時會一直卡著WinRAR 和 7-Zip 也能用可一旦安全軟件在解壓途中隔離了文件你根本察覺不到。Windows 10 1803 以上系統(tǒng)自帶 tar我一般直接用命令解壓既能保留完整目錄結(jié)構(gòu)又能在出錯時看到具體報錯信息。# 新建目標(biāo)目錄后把 zip 解壓到 D:\dev New-Item -ItemType Directory -Force -Path D:\dev tar -xf D:\downloads\flutter_windows_3.0.4-stable.zip -C D:\dev-xf表示展開壓縮包不做額外處理-C指定目標(biāo)根目錄。解壓完后D:\dev下會生成 flutter 目錄。注意我把 zip 放在D:\downloads跟目標(biāo)目錄分開避免誤把壓縮包也解進(jìn) SDK 根目錄。如果習(xí)慣用 PowerShell 的 Expand-Archive語法是Expand-Archive -Path ... -DestinationPath ...但文件一多速度明顯慢解壓這種 1GB 以上的包不推薦。3.2 解壓后的三分鐘檢查解開后先別急著敲命令花三分鐘看目錄結(jié)構(gòu)。第一確認(rèn)D:\dev\flutter\bin\flutter.bat存在這是 Flutter 的命令行入口第二檢查bin\cache目錄里有沒有 dart-sdk 子目錄如果沒有或非常小說明 zip 里緩存不完整第一次運(yùn)行會觸發(fā)下載流程第三順手看一下有沒有文件被安全軟件隔離常見的是 bin 目錄下的 exe 被誤判解壓看起來完整實(shí)際缺文件。# 檢查解壓是否完整命令行入口與 dart-sdk 緩存目錄 Get-ChildItem D:\dev\flutter\bin | Where-Object { $_.Name -match flutter.bat|dart.bat } Get-ChildItem D:\dev\flutter\bin\cache\dart-sdk -ErrorAction SilentlyContinue第一條命令確認(rèn) flutter 和 dart 兩個批處理入口都在第二條強(qiáng)制訪問 dart-sdk 緩存目錄如果返回為空或直接報錯說明 SDK 緩存缺失或壓縮包被截斷。我在部署時碰到過 zip 下載一半就拿來解壓的情況表面看目錄完整等 flutter doctor 跑到一半才發(fā)現(xiàn)引擎構(gòu)件缺失只能重新解壓白白耗掉兩小時。解壓完成后把安全軟件對 Flutter 目錄加個信任能省很多后續(xù)麻煩。3.3 第一次運(yùn)行版本驗(yàn)證與緩存補(bǔ)全解壓完成且目錄檢查無誤后第一次運(yùn)行 flutter.bat 會觸發(fā) SDK 補(bǔ)全流程。網(wǎng)絡(luò)正常的機(jī)器上屏幕會出現(xiàn)引擎構(gòu)件下載提示等它跑完再繼續(xù)操作不要中途 CtrlC否則緩存寫到一半下一次還得從頭拉。這一步跑完SDK 才算真正“活”了。# 進(jìn)入 SDK 根目錄后運(yùn)行版本驗(yàn)證 cd D:\dev\flutter .\bin\flutter.bat --version輸出會帶上 Flutter 3.0.4 與對應(yīng) Dart 版本信息。要提醒的是3.0.4 對應(yīng)哪一版 Dart 以實(shí)際解壓結(jié)果為準(zhǔn)不要自己從別處拷貝 dart-sdk 塞進(jìn)bin\cache版本對不上pub 解析會變得極其怪異。這條命令能正常輸出版本號說明壓縮包主體沒問題后面配置環(huán)境變量才有意義。4. 配置環(huán)境變量與 flutter config三個容易寫錯的路徑4.1 把 flutter\bin 寫進(jìn)用戶 PATHSDK 解壓了不代表 flutter 命令全局可用。命令行進(jìn)程只從 PATH 目錄里找可執(zhí)行文件PATH 里沒有D:\dev\flutter\bin在任意目錄敲 flutter 都會提示“不是內(nèi)部或外部命令”。我推薦寫進(jìn)用戶 PATH 而不是系統(tǒng) PATH用戶級變量只對當(dāng)前賬戶生效不會影響系統(tǒng)里其他管理員賬戶也不會把系統(tǒng) PATH 頂?shù)介L度上限。# 將 flutter\bin 追加到當(dāng)前用戶的 PATH [Environment]::SetEnvironmentVariable(Path, [Environment]::GetEnvironmentVariable(Path,User) ;D:\dev\flutter\bin, User) # 刷新當(dāng)前 PowerShell 會話的 PATH避免重開終端 $env:Path [Environment]::GetEnvironmentVariable(Path,User)第一行先取用戶現(xiàn)有 PATH再拼接D:\dev\flutter\bin寫入 User 級別第三行刷新當(dāng)前會話讓窗口立刻生效。拼接時前面的分號不能漏我見過不少配置完仍找不到命令的人就是漏了分號兩個路徑被連成一個不存在的目錄。另外網(wǎng)上常見的setx Path寫法我盡量少用setx 會在寫入時截斷超過長度限制的內(nèi)容隱患很大。4.2 路徑配置的三個高發(fā)錯誤第一個高頻錯誤是把路徑寫成D:\dev\flutter而不是D:\dev\flutter\bin少一個 bin 子目錄命令找不到入口第二個高頻錯誤是復(fù)制路徑時把末尾斜杠或引號一起粘進(jìn)變量看著沒問題實(shí)際目錄匹配不上第三個高頻錯誤是系統(tǒng) PATH 和用戶 PATH 里同時存在兩個不同版本的 Flutter解析順序決定勝負(fù)越靠前的越優(yōu)先常常出現(xiàn)“明明配了新版跑出來的還是舊版”的錯覺。# 查看當(dāng)前生效的 flutter 路徑以及 PATH 中的搜索順序 where.exe flutterwhere.exe 輸出的第一行就是最終生效的 flutter 命令位置。如果這個路徑跟剛配的不一致去系統(tǒng)變量里找舊版本殘留刪掉后重開終端。我還會留一條應(yīng)急路徑新環(huán)境變量還沒生效時直接調(diào)D:\dev\flutter\bin\flutter.bat繞過 PATH不讓排查卡在“終端沒刷新”這種問題上。4.3 flutter config開關(guān)確認(rèn)與鏡像設(shè)置PATH 配好后的下一步是跑一次 flutter config確認(rèn)當(dāng)前環(huán)境對哪些平臺目標(biāo)開放。Flutter 3.0.4 里 Windows 桌面支持已默認(rèn)啟用config 的作用主要是查看和調(diào)整開關(guān)比如關(guān)閉 Android 檢查項(xiàng)讓 flutter doctor 輸出更干凈或者確認(rèn) Web 支持是否開啟。# 查看當(dāng)前 flutter 配置開關(guān) flutter config --list # 純桌面項(xiàng)目可關(guān)閉 Android 檢查項(xiàng)減少不必要告警 flutter config --no-enable-android--list把所有已知配置項(xiàng)和當(dāng)前值打出來--no-enable-android是開關(guān)型配置告訴 Flutter 不需要準(zhǔn)備 Android 工具鏈。如果項(xiàng)目只有 Windows 桌面需求關(guān)掉 Android 能省掉安裝整套 Android Studio 的時間。等以后真要出 Android 包再執(zhí)行flutter config --enable-android打開即可不會污染現(xiàn)有環(huán)境。首次運(yùn)行如果依賴下載很慢就涉及另一個配置PUB_HOSTED_URL 與 FLUTTER_STORAGE_BASE_URL。這兩個環(huán)境變量分別控制 pub 包倉庫與引擎構(gòu)件下載地址。常見做法是把兩個變量一起指到鏡像根地址只改其中一個會出現(xiàn)依賴能解析但引擎仍走默認(rèn)地址的半吊子狀態(tài)。# 示例為當(dāng)前會話設(shè)置鏡像源實(shí)際地址按本地可達(dá)的鏡像根填寫 $env:PUB_HOSTED_URL https://mirror.example/pub $env:FLUTTER_STORAGE_BASE_URL https://mirror.example flutter pub cache repairpub cache repair會把本地 pub 緩存重新刷一遍適用于換完鏡像后修復(fù)之前殘留的半截下載。我一般把鏡像地址放在用戶環(huán)境變量里不寫進(jìn)工程配置避免把個人網(wǎng)絡(luò)設(shè)置帶進(jìn)團(tuán)隊(duì)倉庫。要注意 PUB_HOSTED_URL 得能直接對應(yīng) pub 倉庫根拼錯一層路徑pub get 會報無法解析或直接超時掛住。5. 常見問題與排查3.0.4 安裝期最容易翻車的位置5.1 找不到 Gitflutter 命令的第一個攔路虎現(xiàn)象解壓完成PATH 也配好運(yùn)行flutter --version終端立刻報 “Unable to locate git” 或提示 git 不是有效命令。原因flutter.bat 的啟動腳本會調(diào)用 git 獲取版本元數(shù)據(jù)這一步與是否用 git clone 安裝 Flutter 無關(guān)。很多人把這份 zip 當(dāng)成純離線包直接忽略 Git 依賴命令在入口就被擋回來。解決安裝 Git for Windows并把 Git 的 bin 目錄加入 PATH。安裝時保持默認(rèn)的“讓 git 可用”選項(xiàng)不要手動改 bin 路徑。裝完后先執(zhí)行where.exe git確認(rèn)能找到再跑 flutter 命令。5.2 Visual Studio 工具鏈未裝完整桌面構(gòu)建中途退出現(xiàn)象flutter doctor 的 Visual Studio 檢查項(xiàng)打紅叉運(yùn)行flutter run -d windows時構(gòu)建輸出里出現(xiàn)類似 CMake 找不到編譯器的錯誤構(gòu)建進(jìn)程幾秒內(nèi)退出。原因構(gòu)建 Windows 桌面程序依賴 VS 的“使用 C 的桌面開發(fā)”工作負(fù)載。只裝 VS 主體不裝這個負(fù)載MSVC 編譯器與 Windows SDK 都不齊全CMake 階段的編譯動作無法完成。解決打開 VS Installer勾選“使用 C 的桌面開發(fā)”同時確認(rèn)安裝了 Windows SDK 組件如果不想裝完整 IDE裝 VS Build Tools 并勾選同一負(fù)載也能滿足。裝完重開終端再跑 flutter doctor看到 Visual Studio 檢查項(xiàng)通過后繼續(xù)。5.3 Android SDK 路徑ANDROID_HOME 和 ANDROID_SDK_ROOT 用哪個現(xiàn)象flutter doctor 里 Android toolchain 項(xiàng)報紅提示找不到 Android SDK但機(jī)器里明明裝了 Android Studio。原因Android Studio 有自己的 SDK 路徑設(shè)置沒有把這個路徑暴露給系統(tǒng)環(huán)境變量Flutter 3.0.4 主要靠環(huán)境變量定位 SDK。解決在用戶環(huán)境變量里設(shè)置 ANDROID_SDK_ROOT指向包含 platform-tools 的 SDK 根目錄。早期的 ANDROID_HOME 寫法在新版本里仍被兼容識別但新環(huán)境我統(tǒng)一用 ANDROID_SDK_ROOT避免兩個變量指向不同 SDK 帶來的混亂。設(shè)置完重開終端再跑 flutter doctor確認(rèn) Android toolchain 從紅叉變回對勾。5.4 新開終端仍然找不到 flutter現(xiàn)象PATH 追加成功當(dāng)前會話里 where.exe flutter 能定位命令但關(guān)掉終端重開輸入 flutter 依然提示“不是內(nèi)部或外部命令”。原因環(huán)境變量更新沒有傳遞到新進(jìn)程或者終端從父進(jìn)程繼承了一份舊 PATH另一類情況是用戶 PATH 長度逼近上限系統(tǒng)拼接時把后半截直接截斷。解決關(guān)掉所有已打開的終端窗口再重開不要點(diǎn)終端里的重載按鈕應(yīng)付。若仍無效執(zhí)行where.exe flutter看解析結(jié)果并打開用戶環(huán)境變量編輯框檢查內(nèi)容發(fā)現(xiàn)被截斷就把一些無效的舊路徑清掉給新路徑留出空間。臨時應(yīng)急直接調(diào)用D:\dev\flutter\bin\flutter.bat下次登錄后再做徹底檢查。5.5 pub 依賴?yán)粍覴esolving dependencies 卡死的真相現(xiàn)象flutter pub get 一直停在 “Resolving dependencies...” 狀態(tài)進(jìn)度條不動最終超時或報網(wǎng)絡(luò)錯誤。原因工程首次解析依賴時會訪問 pub 包倉庫并下載索引直連官方源速度不佳時這個階段會持續(xù)很久某些環(huán)境下還會因握手被環(huán)境影響而掛起。解決先把 PUB_HOSTED_URL 和 FLUTTER_STORAGE_BASE_URL 一起指到同一套鏡像地址再執(zhí)行flutter pub cache repair重建本地緩存。如果公司內(nèi)網(wǎng)有制品庫直接把 PUB_HOSTED_URL 指到內(nèi)網(wǎng)地址也成立。兩個變量必須配套只設(shè)其中一個會在構(gòu)建階段遇到“包能解析、引擎下不動”的怪癥狀。6. 裝完如何驗(yàn)證跑通flutter doctor 到第一個 Windows 桌面 demo6.1 驗(yàn)證流程不是一條命令是四條環(huán)境配完別急著拿現(xiàn)有項(xiàng)目當(dāng)驗(yàn)證。我有一套固定驗(yàn)收流程先看 flutter doctor 的輸出狀態(tài)再看 flutter devices 枚舉到的設(shè)備然后新建一個干凈項(xiàng)目最后用 flutter run -d windows 實(shí)打?qū)嵟芤淮巫烂鏄?gòu)建。這套流程走完不到十分鐘但能把 SDK 完整性、工具鏈可用性、桌面構(gòu)建鏈路一次性驗(yàn)完。6.2 完整驗(yàn)收命令與預(yù)期輸出# 一套走完的驗(yàn)收命令 flutter doctor -v flutter devices cd D:\work flutter create quick_check cd quick_check flutter run -d windowsflutter doctor 的輸出能看出三層信息Dart SDK 環(huán)境是否正常、Visual Studio 工具鏈?zhǔn)欠窨捎谩ndroid 檢查項(xiàng)是否被接受或按需關(guān)閉。flutter devices 列出當(dāng)前可用的運(yùn)行目標(biāo)Windows 桌面應(yīng)出現(xiàn)在其中。flutter create 生成新工程時如果網(wǎng)絡(luò)正常會拉取默認(rèn)模板依賴網(wǎng)絡(luò)異常則可能卡在 pub get 階段這一步正好把前面的鏡像配置一起驗(yàn)證。最后 flutter run -d windows 進(jìn)入構(gòu)建日志里出現(xiàn) “Building Windows application...” 說明 CMake 階段已啟動窗口自動彈出且控制臺出現(xiàn)已連接信息就算跑通。6.3 順手驗(yàn)證發(fā)布構(gòu)建debug 模式能跑release 構(gòu)建通常不會差太遠(yuǎn)但我仍會補(bǔ)一條發(fā)布構(gòu)建命令確認(rèn)優(yōu)化模式下的編譯鏈路同樣完整。flutter build windows --release構(gòu)建成功后的產(chǎn)物一般在build\windows\runner\Release目錄下拿到 exe 才算真正確認(rèn)環(huán)境能產(chǎn)出交付物。從那以后我給任何機(jī)器裝 Flutter Windows 環(huán)境都強(qiáng)制自己走一遍 flutter --version、flutter doctor、flutter create 空項(xiàng)目、flutter run -d windows 這條鏈路不再只看單條命令通過就宣布環(huán)境就緒。多花這幾分鐘能省掉后續(xù)在真實(shí)項(xiàng)目里排查工具鏈問題的一個小時。希望這篇記錄能幫你在 3.0.4 這套 zip 上少踩幾個坑。本文還有配套的精品資源點(diǎn)擊獲取