目錄
description bug_report

開始在 macOS 上建立 Flutter iOS 應用

目錄

系統要求

在安裝和執行 Flutter 前，你的 macOS 環境必須滿足以下要求：

硬體要求

你的 macOS Flutter 開發環境必須滿足以下最低硬體要求。

要求 最低 推薦
CPU 核心數 4 8
記憶體 (GB) 8 16
顯示器解析度（畫素） WXGA (1366 x 768) FHD (1920 x 1080)
可用磁碟空間 (GB) 36.0 56.0

軟體要求

要為 iOS 編寫和編譯 Flutter 程式碼，請安裝以下軟體套件。

作業系統

Flutter 支援 macOS 10.15 (Catalina) 或更高版本。本指南假定你的 Mac 預設執行 zsh shell。

如果需要驗證 shell 的設定，請點選展開此部分

macOS 與大多數「類 UNIX」作業系統一樣， macOS 可以支援多種 shell，如 bash、zsh 和 sh。從 2019 年 10 月發布的 macOS Catalina (macOS 10.15) 開始， Zsh 或 zsh 成為了 macOS 的預設 shell。

檢查並將 zsh 設定為預設

  1. 請執行 目錄服務指令行程式 來驗證 zsh 是否被設定為 macOS 的預設 shell。

     $ dscl . -read ~/ UserShell

    應該會列印以下內容。

     UserShell: /bin/zsh

    如果確認為預設，你可以跳過剩餘的步驟。

  2. 如果需要安裝 zsh，請按照 Wiki 中的步驟進行操作。

  3. 如果需要將預設的 shell 更改為 zsh，請執行 chsh 指令。

     $ chsh -s `which zsh`

如果需要瞭解更多關於 macOS 和 zsh 的訊息，請查閱 macOS 文件中的 在 Mac 上使用 zsh 作為預設 shell。

如果你的 Mac 是 Apple silicon 處理器，那麼有些 Flutter 元件就需要透過 Rosetta 2 來轉換適配（詳情）。要在 Apple silicon 處理器上執行所有 Flutter 元件，請執行以下指令來安裝 Rosetta 2。

$ sudo softwareupdate --install-rosetta --agree-to-license

開發工具

下載並安裝以下軟體套件。

  • Xcode 15 除錯和編譯原生 Swift 或 ObjectiveC 程式碼。 Xcode 的安裝包括 Git 2.27 或更高版本來管理原始碼。
  • CocoaPods 1.13 將 Flutter 外掛應用於原生應用。

上述軟體的開發商為這些產品提供支援。如果需要排除安裝的問題，請查閱該產品的文件。

當你在當前版本執行 flutter doctor 的時候，它可能會列出這些軟體套件的其他不同版本。如果出現這種情況，請安裝它推薦的版本。

文字編輯器或整合開發環境 (IDE)

你可以使用任意文字編輯器或整合開發環境 (IDE)，並結合 Flutter 的指令行工具，來使用 Flutter 建立應用程式。

使用帶有 Flutter 擴充套件或外掛的 IDE 會提供程式碼自動補全、語法高亮、widget 編寫輔助、除錯以及其他功能。

以下是熱門的擴充套件外掛：

安裝 Flutter SDK

你可以使用 VS Code Flutter 擴充套件或自行下載安裝 Flutter 壓縮封裝，來安裝 Flutter SDK。

使用 VS Code 安裝 Flutter

在使用以下流程來安裝 Flutter 前，請確保你已經安裝 Visual Studio Code 1.77 或更高版本，以及 Flutter extension for VS Code。

根據 VS Code 的提示，安裝 Flutter

  1. 啟動 VS Code。

  2. 開啟 指令面板 (Command Palette)，按下快捷鍵 Command + Shift + P。

  3. 在 指令面板 (Command Palette) 中輸入 flutter。

  4. 選擇 Flutter: New Project。

  5. VS Code 會提示你在電腦上找到 Flutter SDK。

    1. 如果你已經安裝 Flutter SDK，請單擊 Locate SDK。

    2. 如果你沒有安裝 Flutter SDK, 請單擊 Download SDK。

      如果你沒有按照 開發工具的必要條件 安裝 Git ，單擊該按鈕後會導向至 Flutter 安裝頁面。

  6. 當提示 Which Flutter template? 的時候，請忽略它。可以按下 Esc。你可以在檢查完開發設定後建立初始測試專案。

下載 Flutter SDK

  1. 當對話框 Select Folder for Flutter SDK 顯示時，選擇你想要安裝 Flutter 的位置。

    VS Code 會開啟你預設的位置。你可以選擇其他位置。

    請考慮 ~/development/ 這樣的位置

  2. 單擊 Clone Flutter。

    在下載 Flutter 時，VS Code 會彈出該通知：

    Downloading the Flutter SDK. This may take a few minutes.

    下載需要一些時間。如果你懷疑下載被掛起，請單擊 Cancel 取消下載後，再重新嘗試安裝。

  3. Flutter 一旦完成下載， 輸出 (Output) 面板就會顯示。

    Checking Dart SDK version...
Downloading Dart SDK from the Flutter engine ...
Expanding downloaded archive...

    成功後，VS Code 會彈出該通知：

    Initializing the Flutter SDK. This may take a few minutes.

    初始化時，輸出 (Output) 面板會顯示下面的內容：

    Building flutter tool...
Running pub upgrade...
Resolving dependencies...
Got dependencies.
Downloading Material fonts...
Downloading Gradle Wrapper...
Downloading package sky_engine...
Downloading flutter_patched_sdk tools...
Downloading flutter_patched_sdk_product tools...
Downloading windows-x64 tools...
Downloading windows-x64/font-subset tools...

    該程序還會執行 flutter doctor -v。此時，請忽略該輸出。因為 Flutter Doctor 可能會顯示與本次快速啟動無關的錯誤。

    Flutter 安裝成功後，VS Code 會彈出該通知：

    Do you want to add the Flutter SDK to PATH so it's accessible
in external terminals?

  4. VS Code 可能會顯示一則 Google Analytics 的通知。

    如果你同意，請單擊 OK。

  5. 在所有 Terminal 視窗中啟用 flutter：

    1. 關閉，然後重新開啟所有 Terminal 視窗。

    2. 重新啟動 VS Code。

下載並安裝 Flutter

從歸檔清單中下載 Flutter SDK 壓縮封裝，將壓縮封裝移動到你想要的位置，然後解壓 SDK，以此來安裝 Flutter。

  1. 下載以下 Flutter SDK 最新 stable 版本的壓縮封裝。

    Intel 處理器   Apple Silicon 處理器
    (獲取中…)   (獲取中…)

    關於其他發布渠道和舊版本，請查閱 Flutter SDK 歸檔清單。

    Flutter SDK 應該會下載至 macOS 預設下載目錄： ~/Downloads/。

  2. 建立一個資料夾，用於安裝 Flutter。

    可以考慮在 ~/development/ 中建立一個目錄。

  3. 將 Flutter SDK 壓縮文件 (zip) 解壓到你想要儲存的目錄中。可以使用以下指令進行解壓。

    $ unzip ~/development/flutter_sdk_v1.0.0.zip -d ~/development/

    完成後，Flutter SDK 應該會位於 ~/development/flutter 目錄中。

將 Flutter 新增至 PATH

要在 Terminal 中執行 Flutter 指令，請將 Flutter 新增到 PATH 環境變數中。本指南假定你的 Mac 執行的是最新的預設 shell，zsh。 Zsh 使用 .zshenv 檔案來處理 環境變數。

  1. 啟動你喜歡的文字編輯器。

  2. 如果 ~/.zshenv 檔案存在，請在文字編輯器中開啟 Zsh 環境變數檔案 ~/.zshenv。如果不存在，請建立 ~/.zshenv。

  3. 複製以下內容並貼上到 ~/.zshenv 檔案內的末尾。

    export PATH=$HOME/development/flutter/bin:$PATH

  4. 儲存 ~/.zshenv 檔案。

  5. 請重新啟動所有開啟的終端會話視窗，來應用此更改。

如果你使用其他 shell，請查閱 設定 PATH 的教程。

如果你已經安裝了所有必要條件和 Flutter SDK，你應該就可以在 macOS 上為 iOS 開發 Flutter。

設定 iOS 開發

設定 Xcode

要為 macOS 開發 Flutter 應用，請安裝 Xcode，以便編譯為原生位元組碼。

  1. 請執行以下指令，來設定指令行工具使用已安裝的 Xcode 版本。

     $ sudo sh -c 'xcode-select -s /Applications/Xcode.app/Contents/Developer && xcodebuild -runFirstLaunch'

    使用以上路徑來設定使用最新版本的 Xcode，如果你需要使用其他版本，請自行指定該路徑。

  2. 請執行以下指令，來安裝 iOS 模擬器。

     $ xcodebuild -downloadPlatform iOS

  3. 簽署 Xcode 許可證協定。

     $ sudo xcodebuild -license

請儘量使用最新版本的 Xcode。

設定目標 iOS 裝置

透過使用 Xcode，你可以在 iOS 真機裝置或模擬器上執行 Flutter 應用。

設定 iOS 模擬器

請按照以下步驟操作，來準備在 iOS 模擬器上執行和測試 Flutter 應用。

  1. 請執行以下指令，來啟動模擬器：

     $ open -a Simulator

  2. 使用 64 位模擬器裝置（涵蓋 iPhone 5s 或更高版本）。

    • 從 Xcode 中選擇模擬器裝置型別。

      1. 開啟 Window > Devices and Simulators。

        你還可以使用快捷鍵：Cmd + Shift + 2

      2. 開啟 Devices and Simulators 對話框後，單擊 Simulators。

      3. 從左側清單中選擇一個 Simulator，或按 + 建立一個新的模擬器。

    • 從 Simulator 應用中，開啟 File > Open Simulator > 選擇目標 iOS 裝置。

    • 在模擬器中檢查裝置版本，開啟 Settings 應用 > General > About。

  3. 模擬的高解析度 iOS 裝置可能會溢位你的螢幕。如果在你的 Mac 上出現這種情況，請在 Simulator 應用中更改顯示尺寸。

    顯示尺寸 選單項 快捷鍵
    小尺寸（與真機相同的物理尺寸） Window > Physical Size Cmd + 1
    適中 Window > Point Accurate Cmd + 2
    HD 高解析度（與真機相同的畫素尺寸） Window > Pixel Accurate Cmd + 3
    適應螢幕 Window > Fit Screen Cmd + 4

設定目標 iOS 裝置

你需要執行以下操作，將 Flutter 應用程式部署到 iPhone 或 iPad 真機上：

  • 建立一個 Apple Developer 賬戶。

  • 在 Xcode 中設定真機裝置部署。

  • 建立開發設定檔案 (Provisioning Profile)，並自行簽署證書 (Signing Certificate)。

  • 如果你的應用程式使用 Flutter 外掛，請安裝第三方 CocoaPods 依賴管理器。

建立 Apple ID 和 Apple Developer 賬戶

要測試部署到 iOS 真機，你需要一個 Apple ID。

要在 App Store 發布你的應用程式，你必須註冊 Apple Developer Program。

如果你只需要測試部署應用程式，請完成第 1 步後繼續下一節。

  1. 如果你沒有 Apple ID，請建立一個。

  2. 如果你未註冊 Apple Developer program，請立即註冊。

    瞭解有關會員型別的更多訊息，請查閱 選擇會員資格。

將 iOS 真機連線到 Mac

設定你的 iOS 真機連線到 Xcode。

  1. 將 iOS 裝置連線到 Mac 的 USB 連接埠。

  2. 首次將 iOS 裝置連線到 Mac 時，你的 iOS 裝置會顯示 信任這台電腦嗎？ 的對話框。

  3. 點選 信任。

    Trust Mac

  4. 出現提示時，解鎖你的 iOS 裝置。

在 iOS 16 或更高版本上啟用開發者模式

從 iOS 16 開始，Apple 要求你啟用 開發者模式，以防止惡意軟體。在部署到 iOS 16 或更高版本的裝置之前，請啟用開發者模式。

  1. 點選 設定 > 隱私與安全性 > 開發者模式。

  2. 將 開發者模式 切換為 開啟。

  3. 點選 重新啟動。

  4. 重新啟動 iOS 裝置後，解鎖 iOS 裝置。

  5. 當出現 開啟開發者模式嗎？ 對話框時，點選 開啟。

    對話框會提示開發者模式會降低 iOS 裝置的安全性。

  6. 解鎖你的 iOS 裝置。

啟用開發者程式碼簽名證書 (signing certificates)

在部署到 iOS 真機前，你需要在 Mac 與 iOS 裝置之間建立信任。這需要將簽名的開發者證書載入到 iOS 裝置上。在 Xcode 中籤署應用程式，你需要建立一個開發者設定檔案 (Provisioning Profile)。

請按照 Xcode 簽署流程設定你的專案。

  1. 開啟 Xcode。

  2. 使用 Apple ID 登入 Xcode。

    1. 選擇 Xcode > Settings…

    2. 點選 Accounts。

    3. 點選 +。

    4. 選擇 Apple ID 並點選 Continue。

    5. 出現提示時，請輸入你的 Apple ID 和 Password。

    6. 關閉 Settings 對話框。

    開發和測試支援任意 Apple ID。

  3. 開啟 File > Open…

    你還可以使用快捷鍵：Cmd + O

  4. 導向至 Flutter 專案目錄。

  5. 開啟專案中預設的 Xcode workspace：ios/Runner.xcworkspace。

  6. 在執行按鈕右側的裝置下拉選單中選擇你要部署的 iOS 真機。

    它應該出現在 iOS devices 標題下方。

  7. 在左側導向面板的 Targets 下，選擇 Runner。

  8. 在 Runner 設定窗內，點選 Signing & Capabilities。

  9. 選擇頂部的 All。

  10. 選擇 Automatically manage signing。

  11. 從 Team 下拉選單中選擇一個團隊。

    團隊是在 Apple Developer Account 頁面的 App Store Connect 建立的。如果你尚未建立團隊，可以選擇 個人團隊 (personal team)。

    Team 下拉選單中會顯示名為 你的名稱 (Personal Team) 的選項。

    Xcode account add

    選擇團隊後，Xcode 會執行以下工作。

    1. 建立並下載開發證書

    2. 將裝置註冊到你的賬戶

    3. 根據需要建立並下載設定檔案 (Provisioning Profile)

如果在 Xcode 中自動簽名失敗，請檢查專案的 General > Identity > Bundle Identifier 值是否唯一。

Check the app's Bundle ID

啟用 Mac 和 iOS 裝置之間的信任

首次連線 iOS 真機時，為你的 Mac 和 iOS 裝置上的開發證書啟用信任。

當 裝置連線到 Mac 時，你應該啟用 iOS 對 Mac 的信任。

為 iOS 裝置啟用開發者證書

在不同版本的 iOS 中，啟用證書的方式也不盡相同。

  1. 開啟 iOS 裝置上的 設定。

  2. 點選 通用 > 裝置管理。

  3. 點選你的證書切換為 啟用。

  1. 開啟 iOS 裝置上的 設定。

  2. 點選 通用 > VPN 與裝置管理。

  3. 點選你的證書切換為 啟用。

  1. 開啟 iOS 裝置上的 設定。

  2. 點選 通用 > VPN 與裝置管理。

  3. 在 開發者應用 標題下，你需要找到你的證書。

  4. 點選你的證書。

  5. 點選 信任 “<certificate>“。

  6. 顯示對話框時，點選 信任。

如果出現提示，請在 codesign 想要訪問金鑰… 的對話框中輸入 Mac 密碼，然後點選 始終允許。

在 iOS 裝置上設定無線除錯（可選）

請按照以下步驟來使用 Wi-Fi 連線除錯裝置。

  1. 將 iOS 裝置連線到與 macOS 裝置相同的網路。

  2. 為 iOS 裝置設定密碼。

  3. 開啟 Xcode。

  4. 選擇 Window > Devices and Simulators。

    你還可以使用快捷鍵：Shift + Cmd + 2

  5. 選擇你的 iOS 裝置。

  6. 選擇 Connect via Network。

  7. 一旦裝置名稱旁邊出現網路圖示，請將 iOS 裝置從 Mac 拔下。

如果在使用 flutter run 時沒有看到裝置清單，請延長超時時間。超時預設為 10 秒。要延長超時時間，請將值改為大於 10 的整數。

flutter run --device-timeout 60

安裝 CocoaPods

如果你的應用程式依賴於帶有原生 macOS 程式碼的 Flutter 外掛，請安裝 CocoaPods。該程式會捆綁 Flutter 和 macOS 程式碼之間的各種依賴關係。

請執行以下步驟，安裝並設定 CocoaPods：

  1. 按照 CocoaPods 安裝指南 安裝 cocoapods。

    $ sudo gem install cocoapods

  2. 啟動你喜歡的文字編輯器。

  3. 在文字編輯器中開啟 Zsh 環境變數檔案 ~/.zshenv。

  4. 複製以下內容並貼上到 ~/.zshenv 檔案內的末尾。

    export PATH=$HOME/.gem/bin:$PATH

  5. 儲存 ~/.zshenv 檔案。

  6. 請重新啟動所有開啟的終端會話視窗，來應用此更改。

檢查你的開發設定

help 幫助

執行 Flutter doctor

flutter doctor 指令將檢查 macOS 完整的 Flutter 開發環境的所有元件。

  1. Open 你的 Terminal.

    開啟你的 Terminal。

  2. 要檢查所有元件的安裝情況，請執行以下指令。

    $ flutter doctor

由於你選擇為 iOS 進行開發，因此不需要 所有 元件。如果你遵循本指南，指令結果應該類似於：

Running flutter doctor...
Doctor summary (to see all details, run flutter doctor -v):
[✓] Flutter (Channel stable, 3.19.0, on macOS A.B chipset, locale en)
[!] Android toolchain - develop for Android devices
[!] Chrome - develop for the web
[✓] Xcode - develop for iOS and macOS (Xcode 15)
[!] Android Studio (not installed)
[✓] VS Code (version 1.86)
[✓] Connected device (1 available)
[✓] Network resources

! Doctor found issues in 3 categories.

解決 Flutter doctor 的問題

當 flutter doctor 指令回傳錯誤時，可能是 Flutter、VS Code、Xcode、連線的裝置或者網路資源出錯。

如果 flutter doctor 指令回傳這些元件中的任何一個錯誤，請使用 verbose 標誌再次執行。

$ flutter doctor -v

檢視輸出結果，瞭解可能需要安裝的其他軟體或者需要執行的其他任務。

如果你更改了 Flutter SDK 或其他相關元件的設定，請再次執行 flutter doctor 來檢查安裝。

管理 Flutter SDK

想要瞭解管理 Flutter SDK 安裝的更多訊息，請查閱以下內容。