使用 Flutter 構建 Windows 應用

本頁面討論了使用 Flutter 構建 Windows 應用時的一些獨特注意事項，包括 Shell 整合以及透過 Microsoft Store 分發 Windows 應用的相關內容。

Windows 程式設計介面結合了傳統的 Win32 API、COM 介面以及更現代的 Windows Runtime 庫。由於這些介面均提供基於 C 的 ABI，因此你可以使用 Dart 的外部函式介面庫 (dart:ffi) 來呼叫作業系統提供的服務。FFI 旨在使 Dart 程式能夠高效地呼叫 C 語言庫。它為 Flutter 應用提供了使用 malloc 或 calloc 分配原生記憶體的能力，並支援指標、結構體、回撥以及 long 和 size_t 等 ABI 型別。

有關從 Flutter 呼叫 C 庫的更多資訊，請參閱 使用 dart:ffi 進行 C 互操作。

在實踐中，雖然透過這種方式從 Dart 呼叫基礎的 Win32 API 相對直接，但使用能夠抽象出 COM 程式設計模型複雜性的包裝庫會更加容易。win32 軟體包 提供了一個用於訪問數千個常見 Windows API 的庫，並使用微軟提供的元資料來確保一致性和正確性。該軟體包還包含了各種常見用例的示例，例如 WMI、磁碟管理、Shell 整合和系統對話方塊。

許多其他軟體包也建立在此基礎之上，為 Windows 登錄檔、遊戲手柄支援、生物識別儲存、工作列整合 和 序列埠訪問 等提供地道的 Dart 訪問方式，這僅僅是其中幾個例子。

更廣泛地講，許多其他 支援 Windows 的軟體包 也已可用，包括 url_launcher、shared_preferences、file_selector 和 path_provider 等常用包。

雖然你可以選擇任何視覺樣式或主題（包括 Material Design），但一些應用作者可能希望構建符合微軟 Fluent 設計系統 規範的應用。fluent_ui 軟體包是一個 Flutter Favorite，它為現代 Windows 應用中常見的視覺效果和控制元件提供了支援，包括導航檢視、內容對話方塊、彈出視窗、日期選擇器和樹狀檢視控制元件。

此外，微軟還提供了 fluentui_system_icons，這是一個可以讓你在 Flutter 應用中輕鬆呼叫數千個 Fluent 圖示的軟體包。

最後，bitsdojo_window 軟體包提供了對“自繪 (owner draw)”標題欄的支援，允許你用自定義標題欄替換標準的 Windows 標題欄，使其與應用的整體風格保持一致。

當你建立一個 Windows 應用時，Flutter 會生成一個承載 Flutter 的小型 C++ 應用程式。這個“執行程式 (runner app)”負責建立和調整傳統的 Win32 視窗大小，初始化 Flutter 引擎及任何原生外掛，並執行 Windows 訊息迴圈（將相關訊息傳遞給 Flutter 進行進一步處理）。

當然，你可以根據需要更改此程式碼，包括修改應用名稱和圖示，以及設定視窗的初始大小和位置。相關程式碼位於 main.cpp 中，你會發現類似如下的程式碼：

Win32Window::Point origin(10, 10);
Win32Window::Size size(1280, 720);
if (!window.CreateAndShow(L"myapp", origin, size))
{
    return EXIT_FAILURE;
}

將 myapp 替換為你希望在 Windows 標題欄中顯示的標題，並可根據需要調整尺寸和視窗座標。

要更改 Windows 應用程式圖示，請將 windows\runner\resources 目錄中的 app_icon.ico 檔案替換為你想要的圖示。

生成的 Windows 可執行檔名可以透過編輯 windows/CMakeLists.txt 中的 BINARY_NAME 變數來修改。

cmake_minimum_required(VERSION 3.14)
project(windows_desktop_app LANGUAGES CXX)

# The name of the executable created for the application.
# Change this to change the on-disk name of your application.
set(BINARY_NAME "YourNewApp")

cmake_policy(SET CMP0063 NEW)

當你執行 flutter build windows 時，在 build\windows\runner\Release 目錄中生成的可執行檔案將與新設定的名稱一致。

最後，有關應用程式可執行檔案本身的更多屬性可以在 windows\runner 目錄下的 Runner.rc 檔案中找到。在這裡，你可以更改嵌入到 Windows 應用中的版權資訊和應用程式版本，這些資訊會顯示在 Windows 資源管理器的屬性對話方塊中。要更改版本號，請編輯 VERSION_AS_NUMBER 和 VERSION_AS_STRING 屬性；其他資訊可以在 StringFileInfo 塊中進行編輯。

對於大多數應用，使用 flutter run 和 flutter build 命令讓 Flutter 處理編譯過程就足夠了。如果你對執行程式進行了重大修改，或者需要將 Flutter 整合到現有的應用中，你可能希望在 Visual Studio 中載入或編譯該 Flutter 應用。

請按照以下步驟操作：

1. 執行 flutter build windows 以建立 build\ 目錄。

2. 開啟 Windows 執行程式的 Visual Studio 解決方案檔案，它現在位於 build\windows 目錄中，檔名取決於你的 Flutter 應用名稱。

3. 在解決方案資源管理器中，你會看到多個專案。右鍵點選與 Flutter 應用同名的專案，然後選擇設為啟動專案 (Set as Startup Project)。

4. 要生成必要的依賴項，請選擇生成 (Build) > 生成解決方案 (Build Solution)。

   你也可以按 Ctrl + Shift + B。

   要從 Visual Studio 執行 Windows 應用，請轉到除錯 (Debug) > 開始除錯 (Start Debugging)。

   你也可以按 F5。

5. 使用工具欄根據需要切換 Debug 和 Release 配置。

分發 Windows 應用程式有多種方法，以下是一些選項：

• 使用工具構建 MSIX 安裝程式（在下一節中描述）並將其透過 Microsoft Windows 應用商店分發。此選項不需要手動建立簽名證書，因為它會為你自動處理。
• 構建 MSIX 安裝程式並透過你自己的網站分發。對於此選項，你需要以 .pfx 證書的形式為應用程式提供數字簽名。
• 收集所有必要元件並構建你自己的 zip 檔案。

MSIX 是新的 Windows 應用程式包格式，提供了現代化的打包格式和安裝程式。這種格式既可用於向 Windows 應用商店釋出應用程式，也可用於直接分發應用安裝程式。

為 Flutter 專案建立 MSIX 分發包的最簡單方法是使用 msix pub 軟體包。有關在 Flutter 桌面應用中使用 msix 軟體包的示例，請參閱 Desktop Photo Search 示例。

對於私有部署和使用 MSIX 安裝程式進行測試，你需要以 .pfx 證書的形式為應用程式提供數字簽名。

透過 Windows 應用商店進行部署時，不需要生成 .pfx 證書。Windows 應用商店會處理透過其商店分發的應用程式的證書建立和管理工作。

透過自己的網站託管來分發應用程式，需要一個由 Windows 所信任的證書頒發機構 (CA) 簽名的證書。

請按照以下說明生成自簽名 .pfx 證書。

1. 如果尚未安裝，請下載 OpenSSL 工具包以生成證書。
2. 進入 OpenSSL 的安裝目錄，例如 C:\Program Files\OpenSSL-Win64\bin。
3. 設定環境變數，以便你可以從任何位置訪問 OpenSSL：
   "C:\Program Files\OpenSSL-Win64\bin"
4. 按如下方式生成私鑰：
   openssl genrsa -out mykeyname.key 2048
5. 使用私鑰生成證書籤名請求 (CSR) 檔案：
   openssl req -new -key mykeyname.key -out mycsrname.csr
6. 使用私鑰和 CSR 檔案生成已簽名的證書 (CRT) 檔案：
   openssl x509 -in mycsrname.csr -out mycrtname.crt -req -signkey mykeyname.key -days 10000
7. 使用私鑰和 CRT 檔案生成 .pfx 檔案：
   openssl pkcs12 -export -out CERTIFICATE.pfx -inkey mykeyname.key -in mycrtname.crt
8. 在安裝應用之前，請先在本地計算機的“證書儲存”中將 .pfx 證書安裝為“受信任的根證書頒發機構”。

Flutter 可執行檔案 (.exe) 位於專案的 build\windows\runner\<build mode>\ 目錄下。除了該可執行檔案，你還需要以下內容：

• 來自同一目錄的：

  • 所有 .dll 檔案
  • data 目錄

• Visual C++ 可再發行元件。你可以使用微軟網站上部署示例演練中展示的任何方法，以確保終端使用者擁有 C++ 可再發行元件。如果你使用 application-local 選項，則需要複製：

  • msvcp140.dll
  • vcruntime140.dll
  • vcruntime140_1.dll

  將這些 DLL 檔案放在與可執行檔案及其他 DLL 同一目錄下，並將它們打包進 zip 檔案中。最終的結構看起來應該像這樣：

  Release
  │   flutter_windows.dll
  │   msvcp140.dll
  │   my_app.exe
  │   vcruntime140.dll
  │   vcruntime140_1.dll
  │
  └───data
  │   │   app.so
  │   │   icudtl.dat
  
  ...
  

  content_copy

此時，如果需要，可以將此資料夾新增到 Inno Setup、WiX 等 Windows 安裝程式中，過程相對簡單。

要了解如何使用 Inno Setup 構建 .exe 來分發你的 Flutter 桌面應用，請查閱此逐步指南：Windows 打包指南。