為 Linux 設定 Flutter flavor

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

Flutter flavor 代表一組設定的集合，用來定義 特定版本的應用程式如何建置與執行。 例如，flavor 可以決定一次建置所使用的視窗標題、 應用程式 ID、API 端點、資源集合與日誌設定。

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

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

在 Linux 上，不需要任何專案設定就能使用 --flavor。 既有的 Flutter 專案不需更新範本或修改設定，即可支援 flavor。 當你傳入 --flavor 時，Flutter 會自動隔離建置目錄、 填入 appFlavor，並過濾 flavor 專屬的資源。

只有在你想要依 flavor 區分原生 runner 時， 例如它的 GTK 應用程式 ID 或視窗標題，才需要完成下列選用步驟。 這個範例會設定兩個 flavor，分別名為 staging 與 production。

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

   $ flutter create flavors_example
   $ cd flavors_example
   

   content_copy

2. 在 linux/CMakeLists.txt 中設定各 flavor 專屬的應用程式 ID：

   開啟 linux/CMakeLists.txt，找到 add_subdirectory(${FLUTTER_MANAGED_DIR}) 這一行。 在該行之後立即依 flavor 設定 APPLICATION_ID：

   linux/CMakeLists.txt

   cmake

   # Flutter library and tool build rules.
   set(FLUTTER_MANAGED_DIR "${CMAKE_CURRENT_SOURCE_DIR}/flutter")
   add_subdirectory(${FLUTTER_MANAGED_DIR})
   
   if(DEFINED FLUTTER_APP_FLAVOR)
     if(FLUTTER_APP_FLAVOR STREQUAL "staging")
       set(APPLICATION_ID "com.example.staging")
     elseif(FLUTTER_APP_FLAVOR STREQUAL "production")
       set(APPLICATION_ID "com.example.production")
     endif()
   endif()
   

   content_copy

   APPLICATION_ID 必須在 add_subdirectory(${FLUTTER_MANAGED_DIR}) 之後設定， 因為 FLUTTER_APP_FLAVOR 要到這個位置才會可用， 同時也必須在使用 APPLICATION_ID 的 add_subdirectory("runner") 之前設定。

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

   執行 staging flavor：

   $ flutter run -d linux --flavor staging
   

   content_copy

   執行 production flavor：

   $ flutter run -d linux --flavor production
   

   content_copy

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

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

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

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

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

$ flutter build linux --flavor <flavor_name>

Flutter 會將編譯好的 bundle 輸出到 build/linux/<arch>/<flavor_name>/release/bundle/。

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

$ flutter test --flavor <flavor_name>

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

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

1. 匯入 services 函式庫：

   在你的 Dart 檔案中加入以下 import：

   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 之後， 你可以為每個設定自訂原生設定與資源。

為了在執行階段區分不同的 flavor， 可以為每個 flavor 自訂原生視窗標題。

1. 在 linux/runner/CMakeLists.txt 中，緊接在現有的 APPLICATION_ID 定義之後，將 FLUTTER_APP_FLAVOR 作為前置處理器定義傳入：

   linux/runner/CMakeLists.txt

   cmake

   # Add preprocessor definitions for the application ID.
   add_definitions(-DAPPLICATION_ID="${APPLICATION_ID}")
   
   if(DEFINED FLUTTER_APP_FLAVOR AND NOT FLUTTER_APP_FLAVOR STREQUAL "")
     add_definitions(-DFLUTTER_APP_FLAVOR="${FLUTTER_APP_FLAVOR}")
   endif()
   

   content_copy

2. 在 linux/runner/my_application.cc 中，於 my_application_activate 函式裡 更新視窗標題：

   linux/runner/my_application.cc

   c

     const gchar* window_title = "flavors_example";
   #ifdef FLUTTER_APP_FLAVOR
     if (g_strcmp0(FLUTTER_APP_FLAVOR, "staging") == 0) {
       window_title = "Staging App";
     } else if (g_strcmp0(FLUTTER_APP_FLAVOR, "production") == 0) {
       window_title = "Production App";
     }
   #endif
   

   content_copy

   接著更新 my_application_activate，改用 window_title 取代寫死的字串常值：

   linux/runner/my_application.cc

   c

       gtk_header_bar_set_title(header_bar, window_title);
       // ...
       gtk_window_set_title(window, window_title);
   

   content_copy

在 Linux 上，應用程式圖示不會直接嵌入編譯後的 可執行二進位檔中。 桌面環境是透過 .desktop 啟動器檔案與已安裝的圖示主題來解析應用程式圖示。

若要為每個 flavor 提供不同的圖示或啟動器項目， 請設定你的 Linux 套件格式（例如 Snap、Flatpak 或 Debian 套件），以安裝不同的桌面項目與圖示資源。 若想進一步了解如何打包 Linux 應用程式，請參閱 建置並發布 Linux 桌面應用程式。

如果有些資源只適用於特定的 flavor， 可以設定 Flutter 只在建置該 flavor 時才打包這些資源。 這樣可以避免未使用的資源增加應用程式 bundle 的大小。

若要有條件地打包資源， 請在 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
• 為 Windows 設定 Flutter flavor
• 建置並發布 Linux 桌面應用程式