Flutter 常用 CLI
日常開發用得到的 flutter 指令。安裝與模擬器設定見 安裝與執行。把盼望教會裝到實機的完整順序見文末 裝到 iPhone：盼望教會。指令對過 Flutter stable 3.47.6；某個子指令的完整旗標用 flutter help <command> 看。
環境
| 指令 | 做什麼 |
|---|---|
flutter --version | 看 Flutter、Engine、Dart 版本 |
flutter doctor | 檢查 SDK、Xcode、Android、裝置是否就緒 |
flutter doctor -v | 同上，多印路徑與版本細節 |
flutter upgrade | 把目前 channel 升到最新 |
flutter upgrade --verify-only | 只檢查有沒有新版，不下載 |
flutter channel | 列出 channel，目前使用中的會標出來 |
flutter channel stable | 切到 stable。切完會下載對應產物 |
日常留在 stable。main 是開發線，API 可能還沒穩定。
只做 iOS、暫時不想裝 Android 時，可以把用不到的平台關掉：
flutter config --no-enable-android
flutter config --list
--list 會印出目前所有開關。要恢復就拿掉 no-，例如 flutter config --enable-android。
開專案
flutter create my_app
cd my_app
只做手機、並指定 Bundle ID 前綴：
flutter create --platforms=ios,android --org com.example my_app
--org 會變成 Android 套件名與 iOS Bundle ID 的前綴，例如 com.example.myApp。專案名必須是合法的 Dart 套件名：小寫、底線，不能用連字號。
只要一個幾乎空白的 lib/main.dart：
flutter create --empty my_app
既有專案缺了 ios/ 或 android/ 時，在專案根目錄再跑一次 flutter create . --platforms=ios,android，它會補缺少的平台資料夾。
套件
相依寫在 pubspec.yaml。改完檔案，或剛 clone 下來，先抓套件：
flutter pub get
從終端機加、移除套件（會改 pubspec.yaml 並執行 get）：
flutter pub add http
flutter pub add dev:very_good_analysis
flutter pub remove http
dev: 前綴表示開發相依（dev_dependencies），不會進正式 App。
flutter pub outdated
flutter pub upgrade
flutter pub upgrade --major-versions
outdated 只看哪些套件有新版。upgrade 在 pubspec.yaml 允許的版本範圍內升到最新，並更新 pubspec.lock。--major-versions 會連主要版號一起升，並改寫 pubspec.yaml，升完要看 changelog，API 可能不相容。
裝置與執行
flutter devices
flutter emulators
flutter emulators --launch <emulator-id>
flutter run
flutter run -d <device-id>
-d 吃裝置 id 或名稱，前綴也行，例如 -d iPhone。多個裝置都符合時，Flutter 會請你選。
三種編譯模式：
| 旗標 | 用途 |
|---|---|
--debug | 預設。有 hot reload、斷點、較慢 |
--profile | 量效能。接近 release，仍可接 DevTools |
--release | 上架前的速度與體積。沒有 hot reload |
flutter run --release -d <device-id>
flutter run 停在前景時，可以直接按鍵：
| 按鍵 | 作用 |
|---|---|
r | Hot reload，保留狀態，套上改過的程式 |
R | Hot restart，整個重跑，狀態清空 |
v | 打開 Flutter DevTools |
s | 截圖，存成目前目錄的 flutter.png |
i | 開關 widget inspector |
p | 開關版面輔助線 |
b | 切換亮色 / 暗色 |
o | 模擬不同作業系統 |
d | 脫離：終端機結束，App 繼續在裝置上跑 |
q | 結束 App 並離開 |
h | 列出全部按鍵 |
改了原生設定、pubspec.yaml 的 asset，或加了套件，hot reload 不夠，改按 R，或停掉後重跑 flutter run。
App 已經用 Xcode 或 IDE 跑起來、想從終端機接上 hot reload：
flutter attach -d <device-id>
檢查與測試
flutter analyze
dart format .
dart fix --dry-run
dart fix --apply
flutter test
flutter test test/widget_test.dart
flutter analyze 在這個版本預設把 info 與 warning 都當成失敗（exit code 非 0）。只想看報告、不要擋流程時加 --no-fatal-infos --no-fatal-warnings。
dart format . 只排版，不改語意。dart fix --apply 會套用可自動修的 lint，先用 --dry-run 看它要動哪些檔。
只跑名稱含某個字的測試：
flutter test --plain-name counter
flutter test --coverage
覆蓋率寫到 coverage/lcov.info。
建置
flutter build 產出可安裝或可上傳的檔案，預設是 release。
| 指令 | 產物 |
|---|---|
flutter build apk | Android APK，build/app/outputs/flutter-apk/ |
flutter build appbundle | 上傳 Play 的 AAB，build/app/outputs/bundle/release/ |
flutter build ios | iOS .app，給 Xcode 再封存 |
flutter build ipa | 可上傳 App Store / TestFlight 的 IPA |
flutter build macos | macOS .app |
flutter build web | 靜態網站，輸出在 build/web/ |
帶入編譯期常數（Dart 裡用 String.fromEnvironment 讀）：
flutter build ipa --dart-define=API_URL=https://api.example.com
同一個 key 可以重複傳多次。flavor 用 --flavor <name>，名稱要和 Android product flavor、Xcode scheme 一致。
清掉建置
編譯異常、換過 Flutter 版本，或 lock 檔與本機快取不一致時：
flutter clean
flutter pub get
clean 刪掉 build/ 與 .dart_tool/，不刪原始碼與 pubspec.lock。下次 flutter run 會完整重編。
裝到 iPhone：盼望教會
這次把 flutter-hope-church 裝到「有一種程式叫「湯姆式」」。裝置 ID 是 00008140-000674513893C01C。憑證與 Bundle ID 的分工見 安裝與執行 的實機一節。
1. 確認環境與手機
flutter doctor
flutter devices --device-timeout 15
flutter doctor 確認 Flutter 與 Xcode 是否可用。flutter devices 列出已連接的裝置。當時 Android SDK 沒裝；這次只走 iPhone，可以略過。
用系統指令對 USB 是否接到這支手機：
system_profiler SPUSBDataType
xcrun xctrace list devices
2. 安裝套件、打開 Xcode 簽章
cd flutter-hope-church
flutter pub get
open ios/Runner.xcworkspace
flutter pub get 下載依賴。open 打開 Xcode 專案。簽章在 Xcode 裡完成：
- Xcode → Settings → Accounts，用 Apple ID 登入。
- 選 Runner target → Signing & Capabilities。
- 勾 Automatically manage signing，Team 選 Personal Team。
當時專案寫入的 Team ID 是 8NND3Z97ZW。確認開發憑證已經出現：
security find-identity -v -p codesigning
成功時會看到類似：
Apple Development: coreisdontgu@gmail.com (7MK5FXX7P9)
1 valid identities found
3. 用偵錯模式裝到手機
flutter run -d 00008140-000674513893C01C
第一次會失敗，終端機出現 No valid code signing certificates。登入 Apple ID 並選好 Team 之後，再跑同一次指令。
編譯簽章時，macOS 會跳出鑰匙圈視窗：codesign 想使用「Apple Development: 政洋 朱」。輸入這台 Mac 的登入密碼，按 永遠允許。按拒絕會得到 Command CodeSign failed with a nonzero exit code。
4. 在 iPhone 上信任開發者
簽章通過後 App 會裝上去。第一次打開會顯示「未受信任的開發者」。在手機上：
設定 → 一般 → VPN 與裝置管理 → 開發者 App → 政洋 朱 → 信任
若前一次 flutter run 還卡在找不到 Dart VM Service，先停掉再重跑：
pkill -f "flutter run -d 00008140-000674513893C01C"
flutter run -d 00008140-000674513893C01C
成功時終端機會出現 Syncing files to device 和 Flutter run key commands。這個程序要保持開著，偵錯版才連得上。
5. 改裝正式版
偵錯版從主畫面點圖示會出現：
Debug mode Flutter apps can only be launched from Flutter tooling
正式版可以直接從主畫面打開：
flutter devices
flutter run --release -d 00008140-000674513893C01C
這次正式版編譯約 28 秒，安裝後就在手機上打開了。之後可以拔掉線，直接點 App 圖示啟動。
程式有改、還要用偵錯與熱重載時，手機保持連線，再跑不含 --release 的 flutter run -d 00008140-000674513893C01C。只是想自己開來用，就用 --release。