iOS 平台指南

本指南說明如何設定您的 SDK 開發環境，以將 Cordova 應用程式部署到 iPhone 和 iPad 等 iOS 裝置，以及如何在開發工作流程中選擇性地使用以 iOS 為中心的命令列工具。無論您是想使用這些以平台為中心的 shell 工具，還是跨平台的 Cordova CLI 進行開發，都需要安裝 SDK 工具。有關這兩種開發路徑的比較，請參閱概述。有關 CLI 的詳細資訊，請參閱Cordova CLI 參考。

需求和支援

用於建置 iOS 應用程式的 Apple® 工具只能在 macOS 環境中運作。Xcode® 是 iOS 應用程式開發的主要工具，它整合了 iOS SDK (軟體開發套件)。為了提交到 Apple App Store℠，應用程式必須使用這些 Apple 工具的最新版本建置。

您可以利用 iOS SDK 和 Xcode 整合的 iOS 模擬器來評估許多 Cordova 功能。但是，在最終提交到 App Store 之前，測試應用程式的所有裝置特定功能需要實際的裝置。

下表概述了 Cordova-iOS 各個版本的前提條件。此外，Xcode 也有自己的系統需求，建議參考最低需求和支援的 SDK 文件進行驗證。

安裝需求

Xcode

有兩種方式可以下載 Xcode

• 從 App Store，在 App Store 應用程式中搜尋「Xcode」即可找到。

• 從 Apple Developer Downloads，這需要註冊為 Apple 開發人員。

安裝 Xcode 後，需要啟用幾個命令列工具才能讓 Cordova 執行。從命令列執行

$ xcode-select --install

部署工具

ios-deploy 工具允許您從命令列在 iOS 裝置上啟動 iOS 應用程式。

透過 Homebrew 安裝 ios-deploy，方法是執行

$ brew install ios-deploy

CocoaPods

建置 iOS 應用程式需要 CocoaPods 工具。最低版本要求為 1.8.0，但始終建議使用最新版本。

若要安裝 CocoaPods，請從命令列終端機執行以下命令

$ sudo gem install cocoapods

專案設定

安裝 Xcode 將會設定大部分開始使用原生程式所需的一切。您現在應該可以建立和建置 cordova 專案。有關安裝和使用 CLI 的更多詳細資訊，請參閱建立您的第一個應用程式指南。

部署到模擬器

若要在 iOS 模擬器中預覽應用程式

1. 從 Xcode 開啟工作區檔案 (platforms/ios/HelloWorld.xcworkspace)，或從命令列

    $ open ./platforms/ios/HelloWorld.xcworkspace/
   

2. 確保在左側面板 (1) 中選取了 HelloWorld 專案。

   

3. 從工具列的 Scheme 選單中選取預期的裝置，例如 (2) 中重點標示的 iPhone XR 模擬器。

4. 按下位於 Scheme 左側同一工具列中的 Run 按鈕 (3)。這會在模擬器中建置、部署和執行應用程式。一個獨立的模擬器應用程式會開啟以顯示該應用程式。

   

   一次只能執行一個模擬器，因此如果您想在不同的模擬器中測試應用程式，則需要關閉模擬器應用程式，並在 Xcode 中執行不同的目標。

Xcode 隨附了最新版本的 iPhone 和 iPad 的模擬器。較舊的版本可能可以從 Xcode → Preferences… → Components 面板取得。

部署到裝置

有關部署到裝置的各種需求的詳細資訊，請參閱 Apple 的關於應用程式發布工作流程的「在裝置上啟動您的應用程式」章節。簡而言之，您需要在部署之前執行以下操作

1. 在 iOS Provisioning Portal 中建立佈建描述檔。您可以使用其開發佈建助理來建立和安裝 Xcode 所需的描述檔和憑證。

2. 確認組建設定中「程式碼簽署」區段內的程式碼簽署身份設定已設定為您的佈建描述檔名稱。

若要部署到裝置

1. 使用 USB 纜線將裝置插入您的 Mac。

2. 從 Xcode 視窗的 Scheme 下拉式清單中選取專案的名稱。

3. 從 Device 下拉式清單中選取您的裝置。如果它透過 USB 連接，但仍未出現，請按下 Organizer 按鈕來解決任何錯誤。

4. 按下 Run 按鈕，以在您的裝置上建置、部署和執行應用程式。

簽署應用程式

首先，您應該閱讀程式碼簽署支援頁面和應用程式發布工作流程。

使用旗標

若要簽署應用程式，您需要以下參數

可以使用上述命令列引數指定這些參數給 Cordova CLI build 或 run 命令。

注意：您應該使用雙 -- 來表示這些是以平台為中心的引數，例如

cordova run ios --release -- --codeSignIdentity="iPhone Developer" --developmentTeam=FG35JLLMXX4A --packageType=development.

使用 build.json

或者，您可以在組建設定檔案中指定這些旗標 (預設值：build.json 或將 --buildConfig 旗標新增到相同命令，因此您也可以使用其他檔案名稱，例如 cordova build ios --buildConfig=../customBuild.json)。以下是一個組建設定檔案的範例

對於自動簽署，其中佈建描述檔由 Xcode 自動管理 (建議)

{
    "ios": {
        "debug": {
            "codeSignIdentity": "iPhone Developer",
            "developmentTeam": "FG35JLLMXX4A",
            "packageType": "development",
            "automaticProvisioning": true
        },
        "release": {
            "codeSignIdentity": "iPhone Developer",
            "developmentTeam": "FG35JLLMXX4A",
            "packageType": "app-store",
            "automaticProvisioning": true,
            "authenticationKeyPath": "/path/to/AuthKey_D383SF739.p8",
            "authenticationKeyID": "D383SF739",
            "authenticationKeyIssuerID": "6053b7fe-68a8-4acb-89be-165aa6465141"
        }
    }
}

對於手動簽署，按 UUID 指定佈建描述檔

{
    "ios": {
        "debug": {
            "codeSignIdentity": "iPhone Development",
            "provisioningProfile": "926c2bd6-8de9-4c2f-8407-1016d2d12954",
            "developmentTeam": "FG35JLLMXX4A",
            "packageType": "development"
        },
        "release": {
            "codeSignIdentity": "iPhone Distribution",
            "provisioningProfile": "70f699ad-faf1-4adE-8fea-9d84738fb306",
            "developmentTeam": "FG35JLLMXX4A",
            "packageType": "app-store"
        }
    }
}

也支援混合和比對命令列引數和 build.json 中的參數。命令列引數中的值將優先。

Xcode 組建旗標

如果您有需要將其他組建旗標傳遞給 Xcode 的自訂情況，您可以使用一個或多個 --buildFlag 選項將這些旗標傳遞給 xcodebuild。如果您使用 xcodebuild 內建旗標，它將顯示警告。

cordova build --device --buildFlag="MYSETTING=myvalue" --buildFlag="MY_OTHER_SETTING=othervalue"
cordova run --device --buildFlag="DEVELOPMENT_TEAM=FG35JLLMXX4A" --buildFlag="-scheme TestSchemeFlag"

您也可以在上面的 build.json 中指定 buildFlag 選項 (buildFlag 金鑰的值是字串或字串陣列)。

偵錯

有關 Xcode 隨附的偵錯工具的詳細資訊，請參閱此文章和此影片。

在 Xcode 中開啟專案

適用於 iOS 專案的 Cordova 可以在 Xcode 中開啟。如果您希望使用 Xcode 內建的偵錯/效能分析工具，或者如果您正在開發 iOS 外掛，這會很有用。請注意，在 Xcode 中開啟專案時，建議您不要在 IDE 中編輯程式碼。這將會編輯您專案 platforms 資料夾中的程式碼 (而不是 www)，並且變更可能會被覆寫。請改為編輯 www 資料夾，並透過執行 cordova build 複製您的變更。

希望在 IDE 中編輯其原生程式碼的外掛開發人員應該在使用 cordova plugin add 將其外掛新增至專案時使用 --link 旗標。這將會連結檔案，以便對 platforms 資料夾中外掛檔案的變更會反映在外掛的來源資料夾中 (反之亦然)。

將 ios 平台新增到您的專案並使用 cordova build 建置之後，您可以從 Xcode 中開啟它。按兩下以開啟 ${PROJECT_NAME}/platforms/ios/${PROJECT_NAME}.xcworkspace 檔案，或從終端機開啟 Xcode

$ open -a Xcode platforms/ios

畫面應如下所示

以平台為中心的工作流程

cordova-ios 包含許多腳本，讓平台可以在不使用完整的 Cordova CLI 的情況下使用。相較於跨平台的 cordova CLI，這種開發方式在某些情況下可能會為您提供更廣泛的開發選項。例如，當您部署客製化的 Cordova WebView 以及原生元件時，您需要使用 shell 工具。在使用此開發路徑之前，您仍然必須如上方 需求與支援 所述配置 SDK 環境。

關於以下討論的每個腳本，請參考 Cordova CLI 參考，以取得關於其引數和用法的更多資訊。每個腳本的名稱都與對應的 CLI 命令相符。例如，cordova-ios/bin/create 等同於 cordova create。

若要開始使用，請從 npm 或 Github 下載 cordova-ios 套件。

若要使用此套件建立專案，請執行 bin 資料夾中的 create 腳本。

$ cordova-ios/bin/create ...

若要執行應用程式，請使用 bin 資料夾中的 run 腳本。

$ cordova-ios/bin/run

建立的專案內會有一個名為 cordova 的資料夾，其中包含專案特定 Cordova 命令的腳本 (例如 run、build 等)。

若要在此專案中安裝外掛程式，請使用 Cordova Plugman 實用工具。

升級

請參考 此 文章以取得升級 cordova-ios 版本的說明。

(Mac®、OS X®、Apple®、Xcode®、App Store℠、iPad®、iPhone®、iPod® 和 Finder® 是 Apple Inc. 的商標。)