接過別人做了一半的 Flutter 項目是我這幾年最常遇到的場景之一。壓縮包解開lib目錄下有二十多個.dart文件散在根層級main.dart一千多行網絡請求、頁面跳轉、本地緩存、彈窗全擠在里面assets里圖片按1.png、2.png編號命名。它能跑但你讓我加一個新模塊我得先把那個一千行的文件從頭讀到尾。還有一個反向的場景自己從flutter create開始做一個新項目第一天很爽第二十天開始懷疑人生——不知道該把新寫的文件放在哪同一個功能的相關代碼分居兩地刪一個舊功能要翻五個目錄確認沒有殘留。這兩個場景指向同一個問題一個完整的 Flutter 項目構成它的不只是能編譯通過的代碼而是一套讓第二個人、第二十天之后的你自己還能順暢接手的文件組織秩序。目錄怎么分、根目錄那些不認識的文件各自管什么、資源放哪、路由寫在哪、測試和構建配置怎么和主代碼對齊——這些看起來是工程規(guī)范實際上是每天都要打交道的東西。下面我按從項目根目錄往里走的順序把一套完整 Flutter 項目的構成拆開講一遍包括每個文件為什么存在、為什么這么分、以及我在實際搭建時踩過的那些坑。1. 拆開一個能跑的工程根目錄里每個文件到底管什么執(zhí)行flutter create之后你不寫一行代碼根目錄就已經有十幾個條目了。新手最常見的處理方式是認識的留著不認識的不管.metadata、.gitignore、analysis_options.yaml這三個常年躺在那里沒人碰。但你一旦開始接別人的項目、或者項目要在多臺機器和流水線上跑這些沒人碰的文件就會跳出來咬你一口。我先把它們的職責逐個說清楚。1.1 pubspec.yaml 的三個身份依賴表、資源清單、約束聲明大部分人把pubspec.yaml當成一個依賴列表來用需要什么包就flutter pub add一下完事。它實際承擔三件事而且后面兩件出問題的概率更高。第一是依賴與版本約束。這里的關鍵不是寫了哪些包而是版本約束的寫法。^1.2.3這種 caret 寫法允許次版本號浮動對應用項目來說通常是可以接受的但如果你的項目依賴某個包的行為非常精確比如某個圖表庫的渲染細節(jié)、某個序列化庫對 null 的處理把它寫成1.2.3鎖定反而更安全。同時別忘了environment段里的 SDK 約束——這條決定了這個項目能被哪個版本的 Dart 工具鏈打開團隊里有人用舊版本 IDE 打不開項目八成是這里卡住了。第二是資源聲明。flutter段下的assets列表決定了哪些文件會被打進產物。這里有一個幾乎所有新手都踩過的坑聲明目錄時結尾的斜杠。寫- assets/images/會把該目錄下的文件包含進來寫- assets/images只會包含這個路徑本身而它是個目錄所以實際上什么也沒包含進去。區(qū)別只有一個字符報錯信息還非常隱晦——運行時圖片加載失敗控制臺給你一句Unable to load asset你回頭檢查文件名拼寫檢查半小時。更麻煩的是這個列表不會遞歸assets/images/icons/下的文件必須單獨聲明一行很多人以為聲明了父目錄就自動包含子目錄結果子目錄里的圖全部加載不出來。第三是項目元信息與構建開關。name決定了包名也決定了所有內部 import 的前綴package:your_app/...改它的成本比想象中高version里的后面那串 build number 是提交應用市場時的版本號依據很多人只改前面的語義化版本忘了后面那串。uses-material-design: true這條如果不寫Icons.xxx系列圖標全部渲染成空白方塊這是個非常經典的排查點。字體聲明fonts段則在自定義字體場景下必不可少每個 weight 都要單獨列一項漏一個就會導致FontWeight.w600渲染成默認字重。提示pubspec.lock要提交到版本庫應用項目但不要手動編輯它。團隊里兩個人pubspec.lock沖突時正確做法是取其中一份再重新flutter pub get而不是手工合并那些依賴樹。1.2 平臺殼工程 android/ios/web 的邊界在哪里android/、ios/、web/、macos/、linux/、windows/這六個目錄本質上是同一個 Dart 應用在不同平臺上的殼。它們負責的是 Flutter 管不到的部分應用圖標、啟動頁、權限聲明、簽名配置、原生插件注冊、深鏈配置。很多純 Flutter 開發(fā)者對這幾個目錄有心理陰影看到build.gradle就想繞道走但只要理解它們的邊界日常需要動的就那么幾處。Android 側的常改點集中在android/app/build.gradle現在新項目多半是build.gradle.ktsapplicationId、minSdkVersion、targetSdkVersion、簽名配置、以及buildTypes里的混淆開關。權限相關的聲明在android/app/src/main/AndroidManifest.xml注意 Flutter 項目通常有三個 Manifest 文件main、debug、profile網絡權限在 debug 版里默認是開著的release 版需要自己確認——這是調試一切正常打包上線后接口全掛的頭號原因。iOS 側的關鍵文件是ios/Runner/Info.plist權限描述文案、URL Scheme、ATS 配置和ios/Podfile原生依賴的版本約束、平臺最低版本。Podfile里那行platform :ios, 12.0如果和某個插件要求的最低版本不匹配pod install就會失敗報錯信息指向一堆你不認識的原生庫。這種時候先看報錯里那句required a higher minimum deployment target再去改這行數字比盲試快得多。Web 側相對簡單web/index.html控制頁面外殼、title、以及首屏加載的占位內容。這里有個細節(jié)Flutter Web 首次加載會有一段白屏引擎在下載在index.html里放一個簡單的 loading 遮罩能顯著改善觀感成本卻極低。關于這些目錄要不要提交到版本庫——要。它們是項目的一部分尤其是原生側任何一次改動圖標、權限、簽名都必須被記錄否則換臺機器打包出來的產物就不一樣。1.3 analysis_options.yaml 與 .gitignore不出聲但決定項目壽命analysis_options.yaml這個文件的存在感極低但它決定了整個項目的代碼風格是否統(tǒng)一。新項目默認引入flutter_lints包包含一套官方推薦的規(guī)則集。我的建議是在項目第一天就把團隊約定寫進去而不是等到代碼寫了三個月再來批量修 lint——后者會產生一個幾百文件的巨型改動評審沒法看最后往往不了了之。幾條我實際會打開或關閉的規(guī)則prefer_const_constructors打開對性能有實際收益且能培養(yǎng)習慣、avoid_print打開防止調試用的 print 混進生產代碼、prefer_single_quotes按團隊習慣、always_specify_types建議關閉在 Dart 的強類型推斷下到處寫類型反而是噪音。此外可以針對特定目錄做規(guī)則豁免比如生成的 l10n 文件、.g.dart生成文件用analyzer: exclude:把它們排除在分析之外能大幅減少分析器噪音。.gitignore的策略更簡單粗暴build/、.dart_tool/、.flutter-plugins、*.iml這些必須忽略pubspec.lock必須提交。ios/Pods/和ios/.symlinks/也要忽略但ios/Podfile.lock建議提交它保證團隊每個人的原生依賴版本一致。還有個小細節(jié).metadata這個文件記錄了項目創(chuàng)建時的工具鏈版本信息flutter命令會讀寫它不要手動編輯也不要輕易在沖突時刪除刪掉后某些工具會認為這是一個非標準工程。2. lib 目錄的第一次分層為什么最后都會收斂到 feature-firstlib是整個項目的核心也是分層方案爭論最激烈的地方。我見過三種典型狀態(tài)一是所有文件平鋪在lib根下靠文件名區(qū)分二是按技術層切成models/、views/、services/、utils/幾大塊三是按業(yè)務功能切成features/login/、features/order/、features/profile/。第一種在文件超過三十個之后必然崩盤第二種能撐到中等規(guī)模但在業(yè)務交叉時開始難受第三種是我目前所有新項目的默認選擇。這一節(jié)講清楚為什么。2.1 main.dart 只該干三件事很多項目爛掉的起點就是main.dart。它一開始只有五行然后有人加了個全局配置初始化有人加了個路由表有人把主題也放進來半年后它變成一個八百行、import 了四十個文件、誰都不敢動的東西。我的做法是main.dart只保留三件事——綁定初始化、錯誤捕獲、把控制權交給 bootstrap。具體來說import package:flutter/material.dart; import bootstrap.dart; void main() async { WidgetsFlutterBinding.ensureInitialized(); await bootstrap(); }WidgetsFlutterBinding.ensureInitialized()這行必須在任何依賴平臺通道的操作之前調用否則會拋出Binding has not yet been initialized。本地數據庫初始化、屏幕方向鎖定、SharedPreferences 預熱都屬于這一類它們全部下沉到bootstrap()里。bootstrap.dart則承擔注冊依賴 → 讀取配置 → 決定首屏 → runApp這條鏈路它是唯一知道全局裝配順序的文件。為什么要把這段拆出來因為它可測。直接寫在main()里的初始化流程單元測試沒法調用main會runApp測試環(huán)境里跑不起來。拆成bootstrap()之后你可以在集成測試里先跑一遍裝配、注入一個 mock 的配置源再驗證首屏路由的決策邏輯。這個收益在項目后期排查為什么冷啟動偶發(fā)白屏這類問題時體現得非常明顯。順帶一提app.dart它返回MaterialApp.router或MaterialApp只負責裝配主題、路由、本地化代理、全局 Provider 作用域。頁面的具體內容一律不寫在這里。這樣應用級配置和頁面級實現的邊界就非常清晰改主題不會碰到業(yè)務代碼加頁面也不會碰應用配置。2.2 按層切和按功能切的真實差異這兩種切法的差異不在于哪個更規(guī)范而在于你日常改一個需求時需要同時打開幾個目錄。我用一張表說明對比維度按技術層切models/views/services按功能切features/xxx新增一個功能在 3~5 個目錄各加文件在 1 個目錄內加文件刪除一個功能需全局搜索確認無殘留刪除整個目錄即可新人理解某個業(yè)務需跨目錄拼湊上下文打開一個目錄即可通讀跨功能復用天然共享都在同一層需顯式下沉到 shared/core團隊協(xié)作沖突多人同時改同一層目錄沖突集中在各自 feature適合規(guī)模小型、功能單一的 Demo中大型、多模塊并行的產品按層切的核心問題是耦合度不可見。models/里有五十個模型你從目錄結構上完全看不出OrderModel只被訂單模塊使用、而UserModel被八個模塊依賴等你想刪訂單模塊時才發(fā)現動不了。按功能切之后一個 feature 目錄內的依賴是內聚的跨 feature 的依賴必須走shared/或core/這個必須顯式走出去的動作恰恰讓耦合變得可見可審計。按功能切的代價也很實在三個功能都需要一個帶圓角的頭像組件時你得決定它放哪。我的經驗是設一條明確的閾值——被兩個以上 feature 使用、且不含業(yè)務語義的組件下沉到shared/widgets/含業(yè)務語義的比如訂單狀態(tài)標簽留在 feature 內寧可復制一次。強行把帶業(yè)務的組件抽到公共層后期會因為不同 feature 的需求分化而變成一堆if-else開關這比復制一份代碼的代價大得多。2.3 一份可以直接抄的目錄樹具體落地的目錄結構長這樣我把它當模板用了好幾個項目改動的都是細節(jié)lib/ ├── main.dart # 入口只做綁定與 bootstrap ├── bootstrap.dart # 依賴注冊、配置加載、首屏決策 ├── app.dart # MaterialApp.router裝配主題/路由/l10n ├── core/ # 與業(yè)務無關、全項目共享的能力 │ ├── constants/ # 常量、環(huán)境枚舉、存儲 key │ ├── errors/ # 異常類型、失敗封裝 │ ├── network/ # Dio 客戶端、攔截器、基地址 │ ├── storage/ # 本地存儲封裝 │ ├── theme/ # 顏色、字體、組件主題 │ ├── router/ # 路由表與路由守衛(wèi) │ ├── utils/ # 無狀態(tài)工具函數、擴展方法 │ └── di/ # 依賴注冊入口 ├── features/ │ ├── auth/ │ │ ├── data/ │ │ │ ├── datasources/ # 遠端/本地數據源 │ │ │ ├── models/ # DTO 與序列化 │ │ │ └── repositories/ # 倉儲實現 │ │ ├── domain/ │ │ │ ├── entities/ # 業(yè)務實體 │ │ │ ├── repositories/ # 倉儲抽象 │ │ │ └── usecases/ # 用例 │ │ └── presentation/ │ │ ├── pages/ # 頁面 │ │ ├── widgets/ # 該功能專屬組件 │ │ └── state/ # 狀態(tài)控制器 │ └── home/ ├── shared/ │ ├── widgets/ # 跨功能復用的純 UI 組件 │ └── extensions/ # 跨功能復用的擴展 └── l10n/ # arb 文件若開啟國際化這里要強調domain 層不是必須的。如果你做的是一個數據展示型應用業(yè)務邏輯就是拉接口、顯示列表硬套三層架構會寫出一堆只做轉發(fā)的 usecase純屬自找麻煩。我的判斷標準是這個功能有沒有需要獨立測試的業(yè)務規(guī)則——有就上 domain沒有就data presentation兩層保持輕量。架構是為維護成本服務的不是為圖紙好看服務的。3. 狀態(tài)管理與依賴注入如何落在目錄結構上選狀態(tài)管理框架的討論已經夠多了我更關心的是另一個問題選完之后代碼放在哪。同樣的 Riverpod 項目有人把所有 Provider 塞在一個providers.dart里有人每個 feature 一個state/目錄六個月后的可維護性天差地別。目錄結構其實是架構的 X 光片看一眼就知道這個項目有沒有想清楚。3.1 目錄結構其實是架構的 X 光片判斷一個 Flutter 項目的架構成熟度我一般看三個信號。第一presentation/層里有沒有直接 import 網絡庫或數據庫包——如果有說明數據獲取邏輯沒有被隔離UI 和 IO 焊死在一起改接口要改頁面。第二data/models/下的模型類有沒有混進BuildContext、Widget之類的 UI 類型——如果有說明序列化模型和視圖模型沒分開后期接口字段一變就牽一發(fā)動全身。第三domain/里有沒有 import Flutter 的任何包——理論上 domain 層應該是純 Dart能在無 UI 環(huán)境下跑測試。這三個信號都指向同一件事依賴方向是否單向。健康的依賴流向是presentation → domain ← dataUI 依賴抽象數據實現依賴抽象兩者互不知道對方。目錄結構的作用就是讓這個方向在物理上可見——你從presentation/pages/login_page.dart里看到一行import ../../data/repositories/auth_repository_impl.dart立刻就知道這里越界了連代碼都不用讀。反過來說如果目錄結構只是把文件按名字分了類但依賴關系是網狀亂竄的那這個分層就是文件夾分層除了讓文件樹好看之外沒有任何約束力。真正的分層約束力來自代碼評審時的紅線以及把紅線寫進analysis_options.yaml或者團隊文檔里。3.2 三種主流狀態(tài)管理的文件落位方式不同方案的落位習慣差別挺大我按自己實際用過的整理一下Provider / Riverpod 系核心是聲明與消費分離。Provider 的聲明文件我建議放在 feature 內的state/目錄一個文件聲明該 feature 的所有 Provider命名帶上 feature 前綴authStateProvider、homeListProvider?？?feature 共享的 Provider比如當前登錄用戶放在core/di/或shared/providers/。Riverpod 用代碼生成時有.g.dart伴隨文件記得在.gitignore里做決策——我傾向于不提交生成文件但在 CI 里先跑dart run build_runner build保證產物一致。Bloc 系天然是一個 feature 一組文件xxx_bloc.dart、xxx_event.dart、xxx_state.dart放在presentation/bloc/下即可。Bloc 的好處是文件命名強制暴露職責壞處是樣板代碼多一個小功能三四個文件。如果項目里 Bloc 數量超過二十個我建議做一層再抽象把重復的 loading/error 狀態(tài)收進基類否則狀態(tài)類會膨脹得沒法看。setState 系別笑很多頁面確實只需要setState。這種情況下不需要任何狀態(tài)管理目錄把StatefulWidget寫進pages/即可。我見過為了架構統(tǒng)一把一個純靜態(tài)展示頁也套上 Bloc 的三個文件管一個沒有狀態(tài)變化的頁面純屬浪費。狀態(tài)管理只在有跨組件狀態(tài)共享需求時才引入這是原則。三種方案在目錄上的共同點是狀態(tài)控制器和頁面放在同一個 feature 下不要全局集中。全局集中的后果是刪一個功能時控制器還留在那個大文件里沒人敢動。3.3 get_it 與 ProviderScope注冊入口放在 bootstrap依賴注入的注冊入口只有一處放在core/di/由bootstrap()調用。這里有兩個高頻問題。第一個是注冊順序。如果AuthRepository依賴ApiClient而ApiClient依賴AppConfig注冊時必須先AppConfig、再ApiClient、最后AuthRepository否則運行時拋對象未注冊。項目大了以后這個順序很難維護我的做法是把注冊按模塊拆成registerCore()、registerAuth()、registerHome()幾個函數在bootstrap()里按模塊依賴順序調用并且每個 feature 的注冊函數寫在它自己的目錄下features/auth/di.dart由core/di匯總調用。這樣刪 feature 時注冊代碼也跟著目錄一起刪。第二個是懶加載與提前初始化。get_it的registerLazySingleton是第一次取用時才構造registerSingleton是注冊時立刻構造。對網絡客戶端這種需要讀配置的用懶加載對需要在啟動階段就完成預熱的比如日志上報、崩潰捕獲用立即構造并且await。這兩者混用會導致一個經典現象某個服務在調試時正常、在冷啟動首屏偶發(fā)報錯因為首屏頁面取用它的時候它的依賴還沒就緒。Riverpod 的ProviderScope是另一套邏輯所有 override 在ProviderScope(overrides: [...])里聲明測試時用ProviderScope(overrides: [apiClientProvider.overrideWithValue(mock)])注入假實現。這個機制比 get_it 更適合測試因為它是作用域化的測試之間互不影響。我的項目里常見組合是get_it 管基礎設施網絡、存儲、日志Riverpod 管狀態(tài)兩套并存但職責不重疊。4. 資源、路由、本地化最容易堆在 lib 根目錄的三類東西這三類東西有個共同特點它們不屬于任何一個業(yè)務功能但又必須被業(yè)務功能引用。于是很多人圖省事在lib根目錄下建assets.dart、routes.dart、strings.dart三個大文件全部常量塞進去。前三個月很爽半年后這三個文件各上千行每次改動都提心吊膽。4.1 assets 的目錄規(guī)劃與 pubspec 聲明陷阱資源目錄我建議放在項目根和lib平級而不是lib里面——lib里的非 Dart 文件雖然能被打包但會讓代碼搜索變得嘈雜。標準結構assets/ ├── images/ # 位圖資源 ├── icons/ # 圖標svg 或 png ├── fonts/ # 字體文件 ├── animations/ # lottie / rive 動畫 └── config/ # 靜態(tài) json 配置pubspec.yaml的聲明有幾個必須注意的點我把它們和對應的癥狀列成表寫法實際效果典型癥狀- assets/images不含目錄下任何文件圖片全加載失敗- assets/images/含該目錄直屬文件不含子目錄子目錄圖片加載失敗- assets/fonts/且在fonts:段單獨聲明字體按 weight 注冊漏寫 weight 時字重回退默認命名規(guī)范也值得定一下我習慣用前綴_用途_狀態(tài)的格式比如icon_nav_home_active.png、bg_login_gradient.png。純數字命名1.png、2.png的項目我基本可以斷定它沒有設計稿交接流程后續(xù)換皮膚時會非常痛苦。還有一個實操細節(jié)圖片資源體積。Flutter 打包不會自動壓縮位圖一張 3MB 的背景圖會原樣進包。我的習慣是加一步構建前檢查超過 500KB 的位圖必須確認是否有必要能轉 WebP 的優(yōu)先轉Flutter 全平臺支持純色圖標優(yōu)先用矢量flutter_svg。4.2 路由表集中化的收益路由有兩種寫法命令式Navigator.push(context, MaterialPageRoute(...))和聲明式路由表。前者寫起來快但三個月后你會收獲一堆散落在各頁面的跳轉代碼改一個頁面路徑要全局搜索。我現在的項目一律用集中路由表go_router或 Flutter 自帶的RouterAPI放在core/router/。集中路由表的收益具體有三條。第一路徑字符串只有一處定義用常量類包起來拼錯會編譯報錯而不是運行時 404。第二路由守衛(wèi)有統(tǒng)一入口登錄態(tài)校驗、權限攔截、深鏈參數解析都能在一個redirect回調里處理而不是每個頁面開頭寫一遍if (!loggedIn) return;。第三頁面結構可見打開路由文件就能看到整個應用有哪些頁面、層級關系如何這對接手項目的人極其友好。路由文件我建議按層級拆而不是按數量拆router.dart只負責拼裝routes/auth_routes.dart、routes/home_routes.dart各自聲明本模塊的路由用ShellRoute或嵌套路由組合。這樣刪模塊時路由也跟著走。有一點必須提醒路由表里的路徑是外部契約。如果應用有深鏈或者 Web 版本路徑一改外部鏈接就全廢了。所以路徑命名要在項目初期定好規(guī)范比如統(tǒng)一小寫短橫線后期只增不改。4.3 l10n 的 arb 文件與代碼生成鏈路國際化這塊如果項目確定只做單語言可以完全跳過不要為了以后可能要而提前引入——它會給你帶來一堆AppLocalizations.of(context)!的空安全噪音。但如果確定要做多語言越早引入越好因為后期把硬編碼中文抽出來是個純體力活而且容易漏。標準鏈路是這樣l10n.yaml放在項目根配置 arb 目錄、輸出目錄、模板文件lib/l10n/app_en.arb、app_zh.arb存放鍵值執(zhí)行flutter gen-l10n新版 Flutter 在flutter run時會自動跑生成AppLocalizations。生成文件我建議放在lib/l10n/generated/并加進analysis_options.yaml的 exclude 列表避免 lint 噪音。arb 文件的組織有個經驗按功能拆文件不要一個大app_en.arb塞所有文案。auth_en.arb、home_en.arb分開通過l10n.yaml的arb-dir配合多個模板文件組合或者干脆用一個文件但用前綴分區(qū)auth_loginTitle、home_greeting。前者更清晰后者更省事看團隊規(guī)模選。鍵名的命名規(guī)范一定要在第一天定死loginTitle和login_title混用是后期最大的痛苦來源。5. test 目錄、構建變體與流水線項目完整的最后一塊拼圖前面講的都是應用本身怎么組織但一個完整的工程還包括它的外圍測試怎么寫、多環(huán)境怎么切、自動化怎么跑。這三塊在很多項目里是缺失的缺失的代價不會立刻顯現而是在第一次線上事故、第一次緊急熱修復時集中爆發(fā)。5.1 test 目錄與 lib 的鏡像關系test/目錄的結構應該鏡像lib/。lib/features/auth/domain/usecases/login_usecase.dart對應的測試就是test/features/auth/domain/usecases/login_usecase_test.dart。這個鏡像關系的好處是找測試不用想——你知道代碼在哪就知道測試在哪。測試的層次我按投入產出比排個序domain 層的純邏輯測試性價比最高跑得快、不依賴環(huán)境、能覆蓋核心業(yè)務規(guī)則data 層的序列化測試次之重點測接口返回的畸形數據會不會導致崩潰widget 測試再次之只測關鍵的交互組件和狀態(tài)切換不要試圖用 widget 測試覆蓋所有 UI 細節(jié)維護成本會超過收益集成測試最少只覆蓋兩三條主流程登錄、下單、支付跑在真實設備或模擬器上。flutter create生成的test/widget_test.dart里那個計數器測試新項目第一件事就是刪掉或者替換掉它沒有任何價值留著只會讓人以為這個項目有測試。測試目錄里我還會單獨建test/helpers/放 mock 數據、測試用的 Provider 覆蓋、fake 實現避免每個測試文件重復造輪子。有個細節(jié)值得說test/和integration_test/是兩個不同目錄。前者跑在 Dart VM 上速度快flutter test就能跑后者跑在設備上flutter test integration_test/需要連設備或模擬器。CI 里我一般只跑前者作為必過門禁后者放在 nightly 或者發(fā)布前的手動觸發(fā)。5.2 flavors 與多環(huán)境配置的落地開發(fā)、測試、生產三套環(huán)境配置不能硬編碼在代碼里。方案有兩層編譯期注入用--dart-define構建期配置用 Flutter flavors。--dart-define的用法是flutter run --dart-defineAPI_BASE_URLhttps://xxx代碼里通過String.fromEnvironment(API_BASE_URL)讀取。它的優(yōu)點是簡單、不需要改原生配置缺點是不能存在多個值同時在手每次切換要改命令而且不小心會把密鑰打進產物所以密鑰絕對不要用 dart-define 傳那個不是加密的。flavors 則是在原生的構建系統(tǒng)里定義多個變體。Android 側在build.gradle里配productFlavors { dev {} prod {} }可以給每個變體不同的applicationId后綴這樣開發(fā)版和正式版能同時裝在一臺機器上這個體驗提升非常明顯iOS 側配xcconfig文件。這條路配置成本高一些但能讓圖標、應用名、包名、簽名全部區(qū)分開。我的實際做法是兩者結合flavor 區(qū)分為dev/prod兩套殼環(huán)境的細粒度配置接口地址、開關用--dart-define或者config/dev.json靜態(tài)文件在啟動時加載。配置讀取統(tǒng)一收在core/config/下暴露一個AppConfig對象其他代碼一律從它取絕不出現散落的String.fromEnvironment。5.3 CI 上的四條命令流水線不需要很復雜四條命令能兜住大部分問題flutter pub get dart run build_runner build --delete-conflicting-outputs # 若使用代碼生成 flutter analyze --fatal-infos flutter testflutter analyze加--fatal-infos是關鍵默認情況下 info 級別的 lint 不會讓命令失敗加上這個參數之后風格問題也會阻斷合并。這看起來很嚴格但它是讓 lint 規(guī)則真正生效的唯一辦法——只要有一條路可以繞過三個月后規(guī)則就形同虛設。構建產物那一步flutter build apk --flavor prod --dart-define...。這里有個坑如果項目用了代碼生成freezed、json_serializable、riverpod_generator構建機上必須先跑build_runner否則報找不到 xxx.g.dart。如果本地提交了生成文件要注意 CI 上重新生成的結果和提交的可能不一致生成器版本不同所以我的建議是統(tǒng)一不提交生成文件CI 每次重新生成環(huán)境一致性更好。6. 從零搭骨架的順序與幾個反復踩到的坑講了這么多構成要素最后說一下實際動手時的順序。這個順序很重要因為有些東西事后補成本極低有些東西事后改成本極高。6.1 我建議的搭建順序第一步定包名和應用名。flutter create --org com.yourcompany --project-name your_app這一步定了之后applicationId、iOS Bundle ID、package:前綴全都跟著走。事后改包名的成本是重新創(chuàng)建一個項目再搬代碼非常痛苦。所以哪怕你還沒想好產品名也先把 org 和項目名想清楚。第二步配 lint 和目錄骨架。analysis_options.yaml先落地core/、features/、shared/三個空目錄建好哪怕里面只有一個.gitkeep。骨架先立起來的意義在于后面每寫一個文件都有明確去處不會因為暫時先放這而產生技術債。第三步配主題和路由。core/theme/里定顏色、字號、圓角、間距這幾個基礎 tokencore/router/里定路由表和守衛(wèi)。這兩塊是全局性的定得越早后面頁面開發(fā)越統(tǒng)一。第四步配網絡層和錯誤模型。core/network/里封裝好客戶端、攔截器、統(tǒng)一錯誤類型core/errors/定好失敗分類網絡失敗、業(yè)務失敗、解析失敗。這塊定得早各個 feature 的數據層就能按統(tǒng)一模式寫不會出現這個模塊用 try-catch 返回 null那個模塊拋異常的混亂。第五步再開始寫第一個 feature。寫完第一個 feature 之后回頭檢查一次目錄結構把不合適的地方調整掉。第一個 feature 是最好的壓力測試它會把骨架的問題全部暴露出來。此時改動成本很低等到五個 feature 寫完再調整就是重構了。第六步補測試和 CI。在只有一兩個 feature 的時候把測試和流水線打通成本最低。等代碼量大了再補人會本能地抵觸。6.2 五個反復出現的坑坑一assets目錄聲明的斜杠。前面提過了但它值得再強調一次因為它的癥狀圖片加載失敗和原因少一個斜杠之間隔得太遠新人平均要花半小時才能定位。我的做法是在pubspec.yaml里給資源聲明加注釋寫明目錄必須帶結尾斜杠?？佣ebug 能跑、release 崩。八成是混淆或者權限問題。Android release 構建默認開啟代碼壓縮某些反射式的序列化、原生插件的類名會被裁掉需要在proguard-rules.pro里保留。另外 release 版的AndroidManifest.xml不合并 debug 版里的網絡權限接口請求會靜默失敗。排查方法是先在本地跑一次flutter run --release把問題暴露在開發(fā)階段而不是發(fā)布階段?？尤?g.dart生成文件的沖突。多人協(xié)作時兩個人同時改了帶freezed的模型生成文件沖突出現在合并請求里。解決辦法就是前面說的生成文件進.gitignoreCI 統(tǒng)一生成。切換過去的那一次要清一次緩存git rm --cached把所有已跟蹤的生成文件移除?？铀膄eature 之間的循環(huán)依賴。features/order引用了features/user的實體features/user又引用了features/order的模型Dart 編譯器不會直接報錯但依賴關系變成了一團亂麻。我的處理方式是出現第一個跨 feature 引用時就把被引用的實體下沉到domain/entities/或者shared/models/同時約定feature 之間不允許直接 import寫進評審清單?？游錶ib根目錄的文件不斷堆積。只要lib根下允許存在業(yè)務文件就一定會有人往里丟。我的做法是lib根下只留main.dart、app.dart、bootstrap.dart三個文件任何新增文件必須進子目錄。這條規(guī)則簡單粗暴但執(zhí)行成本極低效果立竿見影。我自己現在的習慣是新項目開完flutter create的第一件事不是寫代碼而是花一個小時把上面這套骨架搭完——lint、目錄、主題、路由、網絡層、配置讀取。這一個小時看起來沒有產出任何功能但它決定了這個項目在第三個月是能順暢加需求還是每加一個需求都要先做一次考古。踩過的坑多了之后會發(fā)現一個完整的 Flutter 項目代碼只是表面讓代碼能長期被改動的組織結構才是底下那層真正支撐它的東西。 Flutter項目結構全解析：從目錄分層到工程化配置
接過別人做了一半的 Flutter 項目是我這幾年最常遇到的場景之一。壓縮包解開lib目錄下有二十多個.dart文件散在根層級main.dart一千多行網絡請求、頁面跳轉、本地緩存、彈窗全擠在里面assets里圖片按1.png、2.png編號命名。它能跑但你讓我加一個新模塊我得先把那個一千行的文件從頭讀到尾。還有一個反向的場景自己從flutter create開始做一個新項目第一天很爽第二十天開始懷疑人生——不知道該把新寫的文件放在哪同一個功能的相關代碼分居兩地刪一個舊功能要翻五個目錄確認沒有殘留。這兩個場景指向同一個問題一個完整的 Flutter 項目構成它的不只是能編譯通過的代碼而是一套讓第二個人、第二十天之后的你自己還能順暢接手的文件組織秩序。目錄怎么分、根目錄那些不認識的文件各自管什么、資源放哪、路由寫在哪、測試和構建配置怎么和主代碼對齊——這些看起來是工程規(guī)范實際上是每天都要打交道的東西。下面我按從項目根目錄往里走的順序把一套完整 Flutter 項目的構成拆開講一遍包括每個文件為什么存在、為什么這么分、以及我在實際搭建時踩過的那些坑。1. 拆開一個能跑的工程根目錄里每個文件到底管什么執(zhí)行flutter create之后你不寫一行代碼根目錄就已經有十幾個條目了。新手最常見的處理方式是認識的留著不認識的不管.metadata、.gitignore、analysis_options.yaml這三個常年躺在那里沒人碰。但你一旦開始接別人的項目、或者項目要在多臺機器和流水線上跑這些沒人碰的文件就會跳出來咬你一口。我先把它們的職責逐個說清楚。1.1 pubspec.yaml 的三個身份依賴表、資源清單、約束聲明大部分人把pubspec.yaml當成一個依賴列表來用需要什么包就flutter pub add一下完事。它實際承擔三件事而且后面兩件出問題的概率更高。第一是依賴與版本約束。這里的關鍵不是寫了哪些包而是版本約束的寫法。^1.2.3這種 caret 寫法允許次版本號浮動對應用項目來說通常是可以接受的但如果你的項目依賴某個包的行為非常精確比如某個圖表庫的渲染細節(jié)、某個序列化庫對 null 的處理把它寫成1.2.3鎖定反而更安全。同時別忘了environment段里的 SDK 約束——這條決定了這個項目能被哪個版本的 Dart 工具鏈打開團隊里有人用舊版本 IDE 打不開項目八成是這里卡住了。第二是資源聲明。flutter段下的assets列表決定了哪些文件會被打進產物。這里有一個幾乎所有新手都踩過的坑聲明目錄時結尾的斜杠。寫- assets/images/會把該目錄下的文件包含進來寫- assets/images只會包含這個路徑本身而它是個目錄所以實際上什么也沒包含進去。區(qū)別只有一個字符報錯信息還非常隱晦——運行時圖片加載失敗控制臺給你一句Unable to load asset你回頭檢查文件名拼寫檢查半小時。更麻煩的是這個列表不會遞歸assets/images/icons/下的文件必須單獨聲明一行很多人以為聲明了父目錄就自動包含子目錄結果子目錄里的圖全部加載不出來。第三是項目元信息與構建開關。name決定了包名也決定了所有內部 import 的前綴package:your_app/...改它的成本比想象中高version里的后面那串 build number 是提交應用市場時的版本號依據很多人只改前面的語義化版本忘了后面那串。uses-material-design: true這條如果不寫Icons.xxx系列圖標全部渲染成空白方塊這是個非常經典的排查點。字體聲明fonts段則在自定義字體場景下必不可少每個 weight 都要單獨列一項漏一個就會導致FontWeight.w600渲染成默認字重。提示pubspec.lock要提交到版本庫應用項目但不要手動編輯它。團隊里兩個人pubspec.lock沖突時正確做法是取其中一份再重新flutter pub get而不是手工合并那些依賴樹。1.2 平臺殼工程 android/ios/web 的邊界在哪里android/、ios/、web/、macos/、linux/、windows/這六個目錄本質上是同一個 Dart 應用在不同平臺上的殼。它們負責的是 Flutter 管不到的部分應用圖標、啟動頁、權限聲明、簽名配置、原生插件注冊、深鏈配置。很多純 Flutter 開發(fā)者對這幾個目錄有心理陰影看到build.gradle就想繞道走但只要理解它們的邊界日常需要動的就那么幾處。Android 側的常改點集中在android/app/build.gradle現在新項目多半是build.gradle.ktsapplicationId、minSdkVersion、targetSdkVersion、簽名配置、以及buildTypes里的混淆開關。權限相關的聲明在android/app/src/main/AndroidManifest.xml注意 Flutter 項目通常有三個 Manifest 文件main、debug、profile網絡權限在 debug 版里默認是開著的release 版需要自己確認——這是調試一切正常打包上線后接口全掛的頭號原因。iOS 側的關鍵文件是ios/Runner/Info.plist權限描述文案、URL Scheme、ATS 配置和ios/Podfile原生依賴的版本約束、平臺最低版本。Podfile里那行platform :ios, 12.0如果和某個插件要求的最低版本不匹配pod install就會失敗報錯信息指向一堆你不認識的原生庫。這種時候先看報錯里那句required a higher minimum deployment target再去改這行數字比盲試快得多。Web 側相對簡單web/index.html控制頁面外殼、title、以及首屏加載的占位內容。這里有個細節(jié)Flutter Web 首次加載會有一段白屏引擎在下載在index.html里放一個簡單的 loading 遮罩能顯著改善觀感成本卻極低。關于這些目錄要不要提交到版本庫——要。它們是項目的一部分尤其是原生側任何一次改動圖標、權限、簽名都必須被記錄否則換臺機器打包出來的產物就不一樣。1.3 analysis_options.yaml 與 .gitignore不出聲但決定項目壽命analysis_options.yaml這個文件的存在感極低但它決定了整個項目的代碼風格是否統(tǒng)一。新項目默認引入flutter_lints包包含一套官方推薦的規(guī)則集。我的建議是在項目第一天就把團隊約定寫進去而不是等到代碼寫了三個月再來批量修 lint——后者會產生一個幾百文件的巨型改動評審沒法看最后往往不了了之。幾條我實際會打開或關閉的規(guī)則prefer_const_constructors打開對性能有實際收益且能培養(yǎng)習慣、avoid_print打開防止調試用的 print 混進生產代碼、prefer_single_quotes按團隊習慣、always_specify_types建議關閉在 Dart 的強類型推斷下到處寫類型反而是噪音。此外可以針對特定目錄做規(guī)則豁免比如生成的 l10n 文件、.g.dart生成文件用analyzer: exclude:把它們排除在分析之外能大幅減少分析器噪音。.gitignore的策略更簡單粗暴build/、.dart_tool/、.flutter-plugins、*.iml這些必須忽略pubspec.lock必須提交。ios/Pods/和ios/.symlinks/也要忽略但ios/Podfile.lock建議提交它保證團隊每個人的原生依賴版本一致。還有個小細節(jié).metadata這個文件記錄了項目創(chuàng)建時的工具鏈版本信息flutter命令會讀寫它不要手動編輯也不要輕易在沖突時刪除刪掉后某些工具會認為這是一個非標準工程。2. lib 目錄的第一次分層為什么最后都會收斂到 feature-firstlib是整個項目的核心也是分層方案爭論最激烈的地方。我見過三種典型狀態(tài)一是所有文件平鋪在lib根下靠文件名區(qū)分二是按技術層切成models/、views/、services/、utils/幾大塊三是按業(yè)務功能切成features/login/、features/order/、features/profile/。第一種在文件超過三十個之后必然崩盤第二種能撐到中等規(guī)模但在業(yè)務交叉時開始難受第三種是我目前所有新項目的默認選擇。這一節(jié)講清楚為什么。2.1 main.dart 只該干三件事很多項目爛掉的起點就是main.dart。它一開始只有五行然后有人加了個全局配置初始化有人加了個路由表有人把主題也放進來半年后它變成一個八百行、import 了四十個文件、誰都不敢動的東西。我的做法是main.dart只保留三件事——綁定初始化、錯誤捕獲、把控制權交給 bootstrap。具體來說import package:flutter/material.dart; import bootstrap.dart; void main() async { WidgetsFlutterBinding.ensureInitialized(); await bootstrap(); }WidgetsFlutterBinding.ensureInitialized()這行必須在任何依賴平臺通道的操作之前調用否則會拋出Binding has not yet been initialized。本地數據庫初始化、屏幕方向鎖定、SharedPreferences 預熱都屬于這一類它們全部下沉到bootstrap()里。bootstrap.dart則承擔注冊依賴 → 讀取配置 → 決定首屏 → runApp這條鏈路它是唯一知道全局裝配順序的文件。為什么要把這段拆出來因為它可測。直接寫在main()里的初始化流程單元測試沒法調用main會runApp測試環(huán)境里跑不起來。拆成bootstrap()之后你可以在集成測試里先跑一遍裝配、注入一個 mock 的配置源再驗證首屏路由的決策邏輯。這個收益在項目后期排查為什么冷啟動偶發(fā)白屏這類問題時體現得非常明顯。順帶一提app.dart它返回MaterialApp.router或MaterialApp只負責裝配主題、路由、本地化代理、全局 Provider 作用域。頁面的具體內容一律不寫在這里。這樣應用級配置和頁面級實現的邊界就非常清晰改主題不會碰到業(yè)務代碼加頁面也不會碰應用配置。2.2 按層切和按功能切的真實差異這兩種切法的差異不在于哪個更規(guī)范而在于你日常改一個需求時需要同時打開幾個目錄。我用一張表說明對比維度按技術層切models/views/services按功能切features/xxx新增一個功能在 3~5 個目錄各加文件在 1 個目錄內加文件刪除一個功能需全局搜索確認無殘留刪除整個目錄即可新人理解某個業(yè)務需跨目錄拼湊上下文打開一個目錄即可通讀跨功能復用天然共享都在同一層需顯式下沉到 shared/core團隊協(xié)作沖突多人同時改同一層目錄沖突集中在各自 feature適合規(guī)模小型、功能單一的 Demo中大型、多模塊并行的產品按層切的核心問題是耦合度不可見。models/里有五十個模型你從目錄結構上完全看不出OrderModel只被訂單模塊使用、而UserModel被八個模塊依賴等你想刪訂單模塊時才發(fā)現動不了。按功能切之后一個 feature 目錄內的依賴是內聚的跨 feature 的依賴必須走shared/或core/這個必須顯式走出去的動作恰恰讓耦合變得可見可審計。按功能切的代價也很實在三個功能都需要一個帶圓角的頭像組件時你得決定它放哪。我的經驗是設一條明確的閾值——被兩個以上 feature 使用、且不含業(yè)務語義的組件下沉到shared/widgets/含業(yè)務語義的比如訂單狀態(tài)標簽留在 feature 內寧可復制一次。強行把帶業(yè)務的組件抽到公共層后期會因為不同 feature 的需求分化而變成一堆if-else開關這比復制一份代碼的代價大得多。2.3 一份可以直接抄的目錄樹具體落地的目錄結構長這樣我把它當模板用了好幾個項目改動的都是細節(jié)lib/ ├── main.dart # 入口只做綁定與 bootstrap ├── bootstrap.dart # 依賴注冊、配置加載、首屏決策 ├── app.dart # MaterialApp.router裝配主題/路由/l10n ├── core/ # 與業(yè)務無關、全項目共享的能力 │ ├── constants/ # 常量、環(huán)境枚舉、存儲 key │ ├── errors/ # 異常類型、失敗封裝 │ ├── network/ # Dio 客戶端、攔截器、基地址 │ ├── storage/ # 本地存儲封裝 │ ├── theme/ # 顏色、字體、組件主題 │ ├── router/ # 路由表與路由守衛(wèi) │ ├── utils/ # 無狀態(tài)工具函數、擴展方法 │ └── di/ # 依賴注冊入口 ├── features/ │ ├── auth/ │ │ ├── data/ │ │ │ ├── datasources/ # 遠端/本地數據源 │ │ │ ├── models/ # DTO 與序列化 │ │ │ └── repositories/ # 倉儲實現 │ │ ├── domain/ │ │ │ ├── entities/ # 業(yè)務實體 │ │ │ ├── repositories/ # 倉儲抽象 │ │ │ └── usecases/ # 用例 │ │ └── presentation/ │ │ ├── pages/ # 頁面 │ │ ├── widgets/ # 該功能專屬組件 │ │ └── state/ # 狀態(tài)控制器 │ └── home/ ├── shared/ │ ├── widgets/ # 跨功能復用的純 UI 組件 │ └── extensions/ # 跨功能復用的擴展 └── l10n/ # arb 文件若開啟國際化這里要強調domain 層不是必須的。如果你做的是一個數據展示型應用業(yè)務邏輯就是拉接口、顯示列表硬套三層架構會寫出一堆只做轉發(fā)的 usecase純屬自找麻煩。我的判斷標準是這個功能有沒有需要獨立測試的業(yè)務規(guī)則——有就上 domain沒有就data presentation兩層保持輕量。架構是為維護成本服務的不是為圖紙好看服務的。3. 狀態(tài)管理與依賴注入如何落在目錄結構上選狀態(tài)管理框架的討論已經夠多了我更關心的是另一個問題選完之后代碼放在哪。同樣的 Riverpod 項目有人把所有 Provider 塞在一個providers.dart里有人每個 feature 一個state/目錄六個月后的可維護性天差地別。目錄結構其實是架構的 X 光片看一眼就知道這個項目有沒有想清楚。3.1 目錄結構其實是架構的 X 光片判斷一個 Flutter 項目的架構成熟度我一般看三個信號。第一presentation/層里有沒有直接 import 網絡庫或數據庫包——如果有說明數據獲取邏輯沒有被隔離UI 和 IO 焊死在一起改接口要改頁面。第二data/models/下的模型類有沒有混進BuildContext、Widget之類的 UI 類型——如果有說明序列化模型和視圖模型沒分開后期接口字段一變就牽一發(fā)動全身。第三domain/里有沒有 import Flutter 的任何包——理論上 domain 層應該是純 Dart能在無 UI 環(huán)境下跑測試。這三個信號都指向同一件事依賴方向是否單向。健康的依賴流向是presentation → domain ← dataUI 依賴抽象數據實現依賴抽象兩者互不知道對方。目錄結構的作用就是讓這個方向在物理上可見——你從presentation/pages/login_page.dart里看到一行import ../../data/repositories/auth_repository_impl.dart立刻就知道這里越界了連代碼都不用讀。反過來說如果目錄結構只是把文件按名字分了類但依賴關系是網狀亂竄的那這個分層就是文件夾分層除了讓文件樹好看之外沒有任何約束力。真正的分層約束力來自代碼評審時的紅線以及把紅線寫進analysis_options.yaml或者團隊文檔里。3.2 三種主流狀態(tài)管理的文件落位方式不同方案的落位習慣差別挺大我按自己實際用過的整理一下Provider / Riverpod 系核心是聲明與消費分離。Provider 的聲明文件我建議放在 feature 內的state/目錄一個文件聲明該 feature 的所有 Provider命名帶上 feature 前綴authStateProvider、homeListProvider?？?feature 共享的 Provider比如當前登錄用戶放在core/di/或shared/providers/。Riverpod 用代碼生成時有.g.dart伴隨文件記得在.gitignore里做決策——我傾向于不提交生成文件但在 CI 里先跑dart run build_runner build保證產物一致。Bloc 系天然是一個 feature 一組文件xxx_bloc.dart、xxx_event.dart、xxx_state.dart放在presentation/bloc/下即可。Bloc 的好處是文件命名強制暴露職責壞處是樣板代碼多一個小功能三四個文件。如果項目里 Bloc 數量超過二十個我建議做一層再抽象把重復的 loading/error 狀態(tài)收進基類否則狀態(tài)類會膨脹得沒法看。setState 系別笑很多頁面確實只需要setState。這種情況下不需要任何狀態(tài)管理目錄把StatefulWidget寫進pages/即可。我見過為了架構統(tǒng)一把一個純靜態(tài)展示頁也套上 Bloc 的三個文件管一個沒有狀態(tài)變化的頁面純屬浪費。狀態(tài)管理只在有跨組件狀態(tài)共享需求時才引入這是原則。三種方案在目錄上的共同點是狀態(tài)控制器和頁面放在同一個 feature 下不要全局集中。全局集中的后果是刪一個功能時控制器還留在那個大文件里沒人敢動。3.3 get_it 與 ProviderScope注冊入口放在 bootstrap依賴注入的注冊入口只有一處放在core/di/由bootstrap()調用。這里有兩個高頻問題。第一個是注冊順序。如果AuthRepository依賴ApiClient而ApiClient依賴AppConfig注冊時必須先AppConfig、再ApiClient、最后AuthRepository否則運行時拋對象未注冊。項目大了以后這個順序很難維護我的做法是把注冊按模塊拆成registerCore()、registerAuth()、registerHome()幾個函數在bootstrap()里按模塊依賴順序調用并且每個 feature 的注冊函數寫在它自己的目錄下features/auth/di.dart由core/di匯總調用。這樣刪 feature 時注冊代碼也跟著目錄一起刪。第二個是懶加載與提前初始化。get_it的registerLazySingleton是第一次取用時才構造registerSingleton是注冊時立刻構造。對網絡客戶端這種需要讀配置的用懶加載對需要在啟動階段就完成預熱的比如日志上報、崩潰捕獲用立即構造并且await。這兩者混用會導致一個經典現象某個服務在調試時正常、在冷啟動首屏偶發(fā)報錯因為首屏頁面取用它的時候它的依賴還沒就緒。Riverpod 的ProviderScope是另一套邏輯所有 override 在ProviderScope(overrides: [...])里聲明測試時用ProviderScope(overrides: [apiClientProvider.overrideWithValue(mock)])注入假實現。這個機制比 get_it 更適合測試因為它是作用域化的測試之間互不影響。我的項目里常見組合是get_it 管基礎設施網絡、存儲、日志Riverpod 管狀態(tài)兩套并存但職責不重疊。4. 資源、路由、本地化最容易堆在 lib 根目錄的三類東西這三類東西有個共同特點它們不屬于任何一個業(yè)務功能但又必須被業(yè)務功能引用。于是很多人圖省事在lib根目錄下建assets.dart、routes.dart、strings.dart三個大文件全部常量塞進去。前三個月很爽半年后這三個文件各上千行每次改動都提心吊膽。4.1 assets 的目錄規(guī)劃與 pubspec 聲明陷阱資源目錄我建議放在項目根和lib平級而不是lib里面——lib里的非 Dart 文件雖然能被打包但會讓代碼搜索變得嘈雜。標準結構assets/ ├── images/ # 位圖資源 ├── icons/ # 圖標svg 或 png ├── fonts/ # 字體文件 ├── animations/ # lottie / rive 動畫 └── config/ # 靜態(tài) json 配置pubspec.yaml的聲明有幾個必須注意的點我把它們和對應的癥狀列成表寫法實際效果典型癥狀- assets/images不含目錄下任何文件圖片全加載失敗- assets/images/含該目錄直屬文件不含子目錄子目錄圖片加載失敗- assets/fonts/且在fonts:段單獨聲明字體按 weight 注冊漏寫 weight 時字重回退默認命名規(guī)范也值得定一下我習慣用前綴_用途_狀態(tài)的格式比如icon_nav_home_active.png、bg_login_gradient.png。純數字命名1.png、2.png的項目我基本可以斷定它沒有設計稿交接流程后續(xù)換皮膚時會非常痛苦。還有一個實操細節(jié)圖片資源體積。Flutter 打包不會自動壓縮位圖一張 3MB 的背景圖會原樣進包。我的習慣是加一步構建前檢查超過 500KB 的位圖必須確認是否有必要能轉 WebP 的優(yōu)先轉Flutter 全平臺支持純色圖標優(yōu)先用矢量flutter_svg。4.2 路由表集中化的收益路由有兩種寫法命令式Navigator.push(context, MaterialPageRoute(...))和聲明式路由表。前者寫起來快但三個月后你會收獲一堆散落在各頁面的跳轉代碼改一個頁面路徑要全局搜索。我現在的項目一律用集中路由表go_router或 Flutter 自帶的RouterAPI放在core/router/。集中路由表的收益具體有三條。第一路徑字符串只有一處定義用常量類包起來拼錯會編譯報錯而不是運行時 404。第二路由守衛(wèi)有統(tǒng)一入口登錄態(tài)校驗、權限攔截、深鏈參數解析都能在一個redirect回調里處理而不是每個頁面開頭寫一遍if (!loggedIn) return;。第三頁面結構可見打開路由文件就能看到整個應用有哪些頁面、層級關系如何這對接手項目的人極其友好。路由文件我建議按層級拆而不是按數量拆router.dart只負責拼裝routes/auth_routes.dart、routes/home_routes.dart各自聲明本模塊的路由用ShellRoute或嵌套路由組合。這樣刪模塊時路由也跟著走。有一點必須提醒路由表里的路徑是外部契約。如果應用有深鏈或者 Web 版本路徑一改外部鏈接就全廢了。所以路徑命名要在項目初期定好規(guī)范比如統(tǒng)一小寫短橫線后期只增不改。4.3 l10n 的 arb 文件與代碼生成鏈路國際化這塊如果項目確定只做單語言可以完全跳過不要為了以后可能要而提前引入——它會給你帶來一堆AppLocalizations.of(context)!的空安全噪音。但如果確定要做多語言越早引入越好因為后期把硬編碼中文抽出來是個純體力活而且容易漏。標準鏈路是這樣l10n.yaml放在項目根配置 arb 目錄、輸出目錄、模板文件lib/l10n/app_en.arb、app_zh.arb存放鍵值執(zhí)行flutter gen-l10n新版 Flutter 在flutter run時會自動跑生成AppLocalizations。生成文件我建議放在lib/l10n/generated/并加進analysis_options.yaml的 exclude 列表避免 lint 噪音。arb 文件的組織有個經驗按功能拆文件不要一個大app_en.arb塞所有文案。auth_en.arb、home_en.arb分開通過l10n.yaml的arb-dir配合多個模板文件組合或者干脆用一個文件但用前綴分區(qū)auth_loginTitle、home_greeting。前者更清晰后者更省事看團隊規(guī)模選。鍵名的命名規(guī)范一定要在第一天定死loginTitle和login_title混用是后期最大的痛苦來源。5. test 目錄、構建變體與流水線項目完整的最后一塊拼圖前面講的都是應用本身怎么組織但一個完整的工程還包括它的外圍測試怎么寫、多環(huán)境怎么切、自動化怎么跑。這三塊在很多項目里是缺失的缺失的代價不會立刻顯現而是在第一次線上事故、第一次緊急熱修復時集中爆發(fā)。5.1 test 目錄與 lib 的鏡像關系test/目錄的結構應該鏡像lib/。lib/features/auth/domain/usecases/login_usecase.dart對應的測試就是test/features/auth/domain/usecases/login_usecase_test.dart。這個鏡像關系的好處是找測試不用想——你知道代碼在哪就知道測試在哪。測試的層次我按投入產出比排個序domain 層的純邏輯測試性價比最高跑得快、不依賴環(huán)境、能覆蓋核心業(yè)務規(guī)則data 層的序列化測試次之重點測接口返回的畸形數據會不會導致崩潰widget 測試再次之只測關鍵的交互組件和狀態(tài)切換不要試圖用 widget 測試覆蓋所有 UI 細節(jié)維護成本會超過收益集成測試最少只覆蓋兩三條主流程登錄、下單、支付跑在真實設備或模擬器上。flutter create生成的test/widget_test.dart里那個計數器測試新項目第一件事就是刪掉或者替換掉它沒有任何價值留著只會讓人以為這個項目有測試。測試目錄里我還會單獨建test/helpers/放 mock 數據、測試用的 Provider 覆蓋、fake 實現避免每個測試文件重復造輪子。有個細節(jié)值得說test/和integration_test/是兩個不同目錄。前者跑在 Dart VM 上速度快flutter test就能跑后者跑在設備上flutter test integration_test/需要連設備或模擬器。CI 里我一般只跑前者作為必過門禁后者放在 nightly 或者發(fā)布前的手動觸發(fā)。5.2 flavors 與多環(huán)境配置的落地開發(fā)、測試、生產三套環(huán)境配置不能硬編碼在代碼里。方案有兩層編譯期注入用--dart-define構建期配置用 Flutter flavors。--dart-define的用法是flutter run --dart-defineAPI_BASE_URLhttps://xxx代碼里通過String.fromEnvironment(API_BASE_URL)讀取。它的優(yōu)點是簡單、不需要改原生配置缺點是不能存在多個值同時在手每次切換要改命令而且不小心會把密鑰打進產物所以密鑰絕對不要用 dart-define 傳那個不是加密的。flavors 則是在原生的構建系統(tǒng)里定義多個變體。Android 側在build.gradle里配productFlavors { dev {} prod {} }可以給每個變體不同的applicationId后綴這樣開發(fā)版和正式版能同時裝在一臺機器上這個體驗提升非常明顯iOS 側配xcconfig文件。這條路配置成本高一些但能讓圖標、應用名、包名、簽名全部區(qū)分開。我的實際做法是兩者結合flavor 區(qū)分為dev/prod兩套殼環(huán)境的細粒度配置接口地址、開關用--dart-define或者config/dev.json靜態(tài)文件在啟動時加載。配置讀取統(tǒng)一收在core/config/下暴露一個AppConfig對象其他代碼一律從它取絕不出現散落的String.fromEnvironment。5.3 CI 上的四條命令流水線不需要很復雜四條命令能兜住大部分問題flutter pub get dart run build_runner build --delete-conflicting-outputs # 若使用代碼生成 flutter analyze --fatal-infos flutter testflutter analyze加--fatal-infos是關鍵默認情況下 info 級別的 lint 不會讓命令失敗加上這個參數之后風格問題也會阻斷合并。這看起來很嚴格但它是讓 lint 規(guī)則真正生效的唯一辦法——只要有一條路可以繞過三個月后規(guī)則就形同虛設。構建產物那一步flutter build apk --flavor prod --dart-define...。這里有個坑如果項目用了代碼生成freezed、json_serializable、riverpod_generator構建機上必須先跑build_runner否則報找不到 xxx.g.dart。如果本地提交了生成文件要注意 CI 上重新生成的結果和提交的可能不一致生成器版本不同所以我的建議是統(tǒng)一不提交生成文件CI 每次重新生成環(huán)境一致性更好。6. 從零搭骨架的順序與幾個反復踩到的坑講了這么多構成要素最后說一下實際動手時的順序。這個順序很重要因為有些東西事后補成本極低有些東西事后改成本極高。6.1 我建議的搭建順序第一步定包名和應用名。flutter create --org com.yourcompany --project-name your_app這一步定了之后applicationId、iOS Bundle ID、package:前綴全都跟著走。事后改包名的成本是重新創(chuàng)建一個項目再搬代碼非常痛苦。所以哪怕你還沒想好產品名也先把 org 和項目名想清楚。第二步配 lint 和目錄骨架。analysis_options.yaml先落地core/、features/、shared/三個空目錄建好哪怕里面只有一個.gitkeep。骨架先立起來的意義在于后面每寫一個文件都有明確去處不會因為暫時先放這而產生技術債。第三步配主題和路由。core/theme/里定顏色、字號、圓角、間距這幾個基礎 tokencore/router/里定路由表和守衛(wèi)。這兩塊是全局性的定得越早后面頁面開發(fā)越統(tǒng)一。第四步配網絡層和錯誤模型。core/network/里封裝好客戶端、攔截器、統(tǒng)一錯誤類型core/errors/定好失敗分類網絡失敗、業(yè)務失敗、解析失敗。這塊定得早各個 feature 的數據層就能按統(tǒng)一模式寫不會出現這個模塊用 try-catch 返回 null那個模塊拋異常的混亂。第五步再開始寫第一個 feature。寫完第一個 feature 之后回頭檢查一次目錄結構把不合適的地方調整掉。第一個 feature 是最好的壓力測試它會把骨架的問題全部暴露出來。此時改動成本很低等到五個 feature 寫完再調整就是重構了。第六步補測試和 CI。在只有一兩個 feature 的時候把測試和流水線打通成本最低。等代碼量大了再補人會本能地抵觸。6.2 五個反復出現的坑坑一assets目錄聲明的斜杠。前面提過了但它值得再強調一次因為它的癥狀圖片加載失敗和原因少一個斜杠之間隔得太遠新人平均要花半小時才能定位。我的做法是在pubspec.yaml里給資源聲明加注釋寫明目錄必須帶結尾斜杠?？佣ebug 能跑、release 崩。八成是混淆或者權限問題。Android release 構建默認開啟代碼壓縮某些反射式的序列化、原生插件的類名會被裁掉需要在proguard-rules.pro里保留。另外 release 版的AndroidManifest.xml不合并 debug 版里的網絡權限接口請求會靜默失敗。排查方法是先在本地跑一次flutter run --release把問題暴露在開發(fā)階段而不是發(fā)布階段?？尤?g.dart生成文件的沖突。多人協(xié)作時兩個人同時改了帶freezed的模型生成文件沖突出現在合并請求里。解決辦法就是前面說的生成文件進.gitignoreCI 統(tǒng)一生成。切換過去的那一次要清一次緩存git rm --cached把所有已跟蹤的生成文件移除?？铀膄eature 之間的循環(huán)依賴。features/order引用了features/user的實體features/user又引用了features/order的模型Dart 編譯器不會直接報錯但依賴關系變成了一團亂麻。我的處理方式是出現第一個跨 feature 引用時就把被引用的實體下沉到domain/entities/或者shared/models/同時約定feature 之間不允許直接 import寫進評審清單?？游錶ib根目錄的文件不斷堆積。只要lib根下允許存在業(yè)務文件就一定會有人往里丟。我的做法是lib根下只留main.dart、app.dart、bootstrap.dart三個文件任何新增文件必須進子目錄。這條規(guī)則簡單粗暴但執(zhí)行成本極低效果立竿見影。我自己現在的習慣是新項目開完flutter create的第一件事不是寫代碼而是花一個小時把上面這套骨架搭完——lint、目錄、主題、路由、網絡層、配置讀取。這一個小時看起來沒有產出任何功能但它決定了這個項目在第三個月是能順暢加需求還是每加一個需求都要先做一次考古。踩過的坑多了之后會發(fā)現一個完整的 Flutter 項目代碼只是表面讓代碼能長期被改動的組織結構才是底下那層真正支撐它的東西。