為 Windows 設定 Flutter flavor

本指南將說明如何為 Windows 桌面應用程式建立 Flutter flavor。

Flutter flavor 代表一組設定的集合， 用來定義特定版本的應用程式如何建置與執行。 例如，flavor 可以決定某次建置的視窗標題、 應用程式圖示、API 端點、資產 (asset) 組合與日誌 (logging) 設定。

在 Windows 上，Flutter 使用 CMake 來設定並建置 原生桌面 runner。 當你搭配 --flavor 旗標執行 flutter run 或 flutter build 時， Flutter 會將 flavor 名稱以 FLUTTER_APP_FLAVOR 變數的形式寫入 windows/flutter/ephemeral/generated_config.cmake， 並將建置輸出隔離在各 flavor 專屬的目錄中。

下表說明當專案定義了兩個 flavor（staging、production） 以及兩種建置模式（debug、release）時， Flutter 所建立的建置目錄：

在 Windows 上傳入 --flavor 不需要任何 CMake 設定。 既有的 Flutter 專案不需要更新範本或變更設定， 即可支援 flavor。 當你傳入 --flavor 時，Flutter 會自動隔離建置目錄、 填入 appFlavor，並篩選出 flavor 專屬的資產。

若要使用範例專案試用 flavor， 請完成以下步驟：

1. 建立一個名為 flavors_example 的新 Flutter 專案：

   $ flutter create flavors_example
   $ cd flavors_example
   

   content_copy

2. 確認你的 flavor 能正確執行：

   執行 staging flavor：

   $ flutter run -d windows --flavor staging
   

   content_copy

   執行 production flavor：

   $ flutter run -d windows --flavor production
   

   content_copy

若要為每個 flavor 自訂原生 runner 設定，例如 視窗標題或應用程式圖示，請參閱 自訂設定。

定義好應用程式的 flavor 之後， 即可使用 Flutter CLI 的 --flavor 旗標 來執行、建置或測試特定的 flavor。

若要在開發期間執行特定的 flavor， 請將 --flavor 選項傳給 flutter run：

$ flutter run -d windows --flavor <flavor_name>

請將 <flavor_name> 替換為你的 flavor 名稱 （例如 staging 或 production）。

若要為特定的 flavor 建置 release 可執行檔， 請將 --flavor 選項傳給 flutter build：

$ flutter build windows --flavor <flavor_name>

Flutter 會將編譯後的可執行檔輸出到 build/windows/<arch>/<flavor_name>/runner/Release/。

--flavor 選項也適用於 flutter test 與 flutter drive， 讓你可以針對特定的 flavor 設定 執行單元測試、元件 (Widget) 測試或整合測試：

$ flutter test --flavor <flavor_name>

加入 flavor 之後， 你可以依據目前啟用的 flavor 調整應用程式行為，例如選擇 API 端點、 切換功能，或設定分析 (analytics) 金鑰。

Flutter 框架在 services 函式庫中提供了 appFlavor 常數， 用來識別執行或建置應用程式時所使用的 flavor。

1. 匯入 services 函式庫：

   將以下 import 加入你的 Dart 檔案：

   dart

   import 'package:flutter/services.dart';
   

   content_copy

2. 讀取 flavor 的值：

   在應用程式邏輯中（通常是 main()）使用 appFlavor 常數， 來處理 flavor 專屬的設定：

   dart

   void main() {
     if (appFlavor == 'production') {
       Config.apiUrl = 'https://api.example.com';
     } else if (appFlavor == 'staging') {
       Config.apiUrl = 'https://staging.api.example.com';
     }
   ​
     runApp(const MyApp());
   }
   

   content_copy

若要依 flavor 區分原生 Windows runner，例如 讓每個 flavor 擁有獨特的視窗標題或應用程式圖示，請設定 CMake，使用 configure_file 來產生 runner 的原始碼與資源檔。

CMake 會在 FLUTTER_APP_FLAVOR 定義之後， 才評估 windows/runner/CMakeLists.txt。 你可以檢查這個變數來設定 flavor 專屬的值， 再使用 configure_file 將這些值代入 C++ runner (main.cpp) 與 Windows 資源指令碼 (Runner.rc) 的範本檔中。

在 windows/runner/CMakeLists.txt 中， 於 add_executable(${BINARY_NAME} ...) 這一行之前加入以下區塊：

# Configure flavor-specific settings.
if(DEFINED FLUTTER_APP_FLAVOR)
  if(FLUTTER_APP_FLAVOR STREQUAL "staging")
    set(RUNNER_APP_ICON "staging.ico")
    set(WINDOW_TITLE "Staging App")
  elseif(FLUTTER_APP_FLAVOR STREQUAL "production")
    set(RUNNER_APP_ICON "production.ico")
    set(WINDOW_TITLE "Production App")
  endif()
else()
  set(RUNNER_APP_ICON "app_icon.ico")
  set(WINDOW_TITLE "${BINARY_NAME}")
endif()

configure_file(
  "${CMAKE_CURRENT_SOURCE_DIR}/main.cpp.in"
  "${CMAKE_CURRENT_SOURCE_DIR}/main.cpp"
  @ONLY
)

configure_file(
  "${CMAKE_CURRENT_SOURCE_DIR}/Runner.rc.in"
  "${CMAKE_CURRENT_SOURCE_DIR}/Runner.rc"
  @ONLY
)

若要在應用程式啟動時顯示 flavor 專屬的視窗標題：

1. 將 windows/runner/main.cpp 重新命名為 windows/runner/main.cpp.in。

2. 在 windows/runner/main.cpp.in 中，找到呼叫 window.Create 的位置， 並將寫死的標題替換為 @WINDOW_TITLE@：

   windows/runner/main.cpp.in

   cpp

     if (!window.Create(L"@WINDOW_TITLE@", origin, size)) {
       return EXIT_FAILURE;
     }
   

   content_copy

   當 CMake 設定建置時， 會將 @WINDOW_TITLE@ 替換為所選 flavor 的視窗標題。

若要為每個 flavor 提供獨特的桌面圖示：

1. 準備 .ico 格式的圖示檔 （例如 staging.ico 與 production.ico）， 並將它們與預設的 app_icon.ico 一起 放在 windows/runner/resources/ 中。

2. 將 windows/runner/Runner.rc 重新命名為 windows/runner/Runner.rc.in。

3. 在 windows/runner/Runner.rc.in 中，找到 IDI_APP_ICON 那一行， 並更新圖示路徑以使用 @RUNNER_APP_ICON@：

   windows/runner/Runner.rc.in

   rc

   IDI_APP_ICON            ICON                    "resources\\@RUNNER_APP_ICON@"
   

   content_copy

   你也可以更新中繼資料字串，例如 FileDescription 與 ProductName，改用 @WINDOW_TITLE@：

   windows/runner/Runner.rc.in

   rc

   VALUE "FileDescription", "@WINDOW_TITLE@" "\0"
   VALUE "ProductName",     "@WINDOW_TITLE@" "\0"
   

   content_copy

如果有些資產只適用於特定的 flavor， 可以設定 Flutter 僅在建置該 flavor 時才打包這些資產。 這樣可以避免不必要的資產增加應用程式套件的大小。

若要有條件地打包資產， 請在 pubspec.yaml 的資產項目中加入 flavors 清單：

flutter:
  assets:
    - assets/common/
    - path: assets/staging/
      flavors:
        - staging
    - path: assets/production/
      flavors:
        - production

若想進一步了解，請參閱 Flutter pubspec 選項中的 assets 欄位。

若要指定在未使用 --flavor 旗標時， 執行或建置所使用的 flavor， 請在 pubspec.yaml 中加入 default-flavor 屬性：

flutter:
  default-flavor: staging

若想進一步了解，請參閱 Flutter pubspec 選項中的 default-flavor 欄位。

如需更多關於 flavor 與桌面部署的資訊， 請參閱以下資源：

• 為 Android 設定 Flutter flavor
• 為 iOS 與 macOS 設定 Flutter flavor
• 為 Linux 設定 Flutter flavor
• 建置並發佈 Windows 桌面應用程式