使用 Flutter 構建 macOS 應用

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

雖然你可以使用任何視覺風格或主題來構建 macOS 應用，但你可能希望對應用進行適配，使其更符合 macOS 的外觀與體驗。Flutter 包含 Cupertino 元件庫，它提供了一套符合當前 iOS 設計語言的元件。其中許多元件（如滑塊、開關和分段控制元件）同樣適用於 macOS。

另外，你可能會發現 macos_ui 包非常適合你的需求。該包提供了實現 macOS 設計語言的元件和主題，包括 MacosWindow 框架和腳手架、工具欄、下拉和彈出按鈕以及模態對話方塊等。

若要分發你的 macOS 應用，你可以選擇透過 macOS App Store 分發，也可以直接分發 .app 檔案（例如透過你自己的網站）。在 macOS App Store 之外分發應用之前，你需要對應用進行公證（Notarization）。

上述兩個流程的第一步都涉及在 Xcode 中處理你的應用。為了能在 Xcode 中編譯應用，你需要先使用 flutter build 命令構建釋出版本，然後開啟 Flutter macOS Runner 應用。

flutter build macos
open macos/Runner.xcworkspace

進入 Xcode 後，請遵循蘋果關於公證 macOS 應用或透過 App Store 分發應用的官方文件。你還應通讀下方的macOS 特定支援部分，以瞭解許可權、應用沙盒和強化執行時對你釋出的應用有何影響。

構建併發布 macOS 應用 頁面提供了將 Flutter 應用釋出到 App Store 的詳細分步指南。

macOS 構建預設配置為簽名狀態，並受應用沙盒（App Sandbox）限制。這意味著如果你想讓 macOS 應用具備特定功能或服務，例如以下功能：

• 訪問網際網路
• 從內建攝像頭捕獲影片和影像
• 訪問檔案

那麼你必須在 Xcode 中設定特定的許可權（entitlements）。下一節將介紹如何進行此操作。

管理沙盒設定是在 macos/Runner/*.entitlements 檔案中進行的。編輯這些檔案時，不應移除原始的 Runner-DebugProfile.entitlements 異常配置（用於支援傳入的網路連線和 JIT），因為它們對於 debug 和 profile 模式的正常執行是必需的。

如果你習慣透過 Xcode 能力（Capabilities）介面管理許可權檔案，請注意，能力編輯器通常只會更新兩個檔案中的其中一個；在某些情況下，它甚至會建立一個全新的許可權檔案，並將專案切換為在所有配置中使用它。這兩種情況都會引發問題。我們建議你直接編輯這些檔案。除非有非常特殊的理由，否則你應該始終對兩個檔案進行相同的修改。

如果你保持應用沙盒處於啟用狀態（如果你打算在 App Store 中分發應用，這是必需的），則在新增某些外掛或其他原生功能時，需要管理應用的許可權。例如，使用 file_chooser 外掛需要新增 com.apple.security.files.user-selected.read-only 或 com.apple.security.files.user-selected.read-write 許可權。另一個常見的許可權是 com.apple.security.network.client，如果你進行任何網路請求，則必須新增此許可權。

例如，如果沒有 com.apple.security.network.client 許可權，網路請求將會失敗，並顯示如下訊息：

flutter: SocketException: Connection failed
(OS Error: Operation not permitted, errno = 1),
address = example.com, port = 443

有關這些主題的更多資訊，請參閱 Apple 開發者網站上的 App Sandbox 和 Entitlements。

如果你選擇在 App Store 之外分發你的應用，則需要對應用進行公證以相容 macOS。這需要啟用“強化執行時（Hardened Runtime）”選項。啟用後，你需要有效的簽名證書才能進行構建。

預設情況下，許可權檔案允許除錯構建使用 JIT，但與應用沙盒一樣，你可能需要管理其他許可權。如果你同時啟用了應用沙盒和強化執行時，則可能需要為同一資源新增多個許可權。例如，訪問麥克風需要同時新增 com.apple.security.device.audio-input（針對強化執行時）和 com.apple.security.device.microphone（針對應用沙盒）。

有關此主題的更多資訊，請參閱 Apple 開發者網站上的 Hardened Runtime。