查閱指南

從零開始打包 iOS

在 Windows 或 Linux 編寫程式碼，在雲端 Mac 完成 iOS 建置。先連上主機，再檢查工具，最後處理相依套件與簽章。

租用一天 查看步驟

已有訂單？先在控制台確認執行個體狀態與連線資訊，請勿將付款憑證當作連線密碼。

先讓環境正常運作

這三個步驟只檢查連線與工具。暫時不要匯入正式環境的憑證，也不要一開始就升級所有相依套件。

  1. 確認連線資訊

    登入控制台，開啟對應的訂單與執行個體詳細資訊。確認節點、執行狀態，以及頁面提供的連線位址、連接埠與憑證。

    連線位址不等於訂單編號。如果執行個體仍在開通中，請先查看狀態；如果出現錯誤，請附上訂單編號提交工單，不要反覆重設設定。

    查看訂單

  2. 登入 macOS

    在本機 VNC 用戶端分別填入位址、連接埠與密碼。第一次連線時先使用較低的解析度，確認鍵盤、滑鼠與視窗操作正常。

    需要使用命令列時，請使用執行個體提供的 SSH 連線資訊。第一次連線時先確認主機指紋；如果指紋異常變更，請停止輸入憑證並查明原因。

    桌面操作卡頓不代表建置已停止。先檢查本機網路，再降低畫面解析度；純建置工作可改用 SSH 執行。

  3. 檢查開發工具

    確認已安裝完整的 Xcode，並至少開啟一次以完成元件初始化。命令列工具應指向這次建置要使用的 Xcode，而不是只指向獨立工具目錄。

    xcode-select -p
xcodebuild -version
xcodebuild -showsdks

    缺少 iOS SDK 時，請先補齊 Xcode 元件。只有在出現授權合約提示時才處理授權；不要靠切換目錄掩蓋 SDK 實際缺失的問題。

使用 Flutter

先檢查 doctor

將專案、相依套件鎖定檔與所需資源一併傳到 Mac。沿用專案現有的 Flutter 版本，先排除環境問題，再修改應用程式的程式碼。

備妥必要工具

準備 Flutter SDK、完整的 Xcode 與 CocoaPods。如果專案指定 Flutter 版本或 Ruby 工具鏈，請先依照儲存庫的設定安裝，避免本機與打包主機使用不同版本。

執行診斷後，逐項處理 iOS 工具鏈提示。裝置連線提示不一定會阻止封存；Xcode、SDK 或簽章設定缺失則必須先處理。

分清兩種驗證方式

只想確認能否成功編譯，可先執行不簽章的 release 建置。這不能取代已簽章的安裝套件，也不能直接作為發佈成品。

準備匯出 .ipa 時，請在 Xcode 的 Signing & Capabilities 中確認 Team、Bundle Identifier、憑證與描述檔，再執行正式打包。

依序執行

flutter --version
flutter doctor -v
flutter pub get
flutter build ios --release --no-codesign
flutter build ipa --release

最後一個指令需要完整的簽章設定。輸出位置與匯出方式請以目前的 Flutter 版本及指令輸出為準；完成後將成品下載到本機驗證。

先確認失敗發生在哪一層，再決定是否清除快取
錯誤線索 優先處理 先不要做
CocoaPods not installed 確認是否已安裝 CocoaPods，以及目前的終端機是否找得到 pod 指令。 不要一開始就刪除整個 iOS 專案。
No profiles / signing 確認 Bundle Identifier、Team 與匯出類型是否相符，並檢查描述檔的有效期限。 不要把相依套件錯誤和簽章錯誤混在一起處理。
Deployment target 對照外掛程式的要求，統一專案與 Podfile 的最低 iOS 版本，再安裝相依套件。 不要只修改一個 target 就直接重試封存。

使用 React Native

鎖定相依套件版本

先查看儲存庫對 Node、Ruby 與套件管理工具的設定。保留鎖定檔，讓打包主機重現團隊現有的環境，而不是重新挑選相依套件版本。

先安裝 JS 相依套件

依照專案的鎖定檔選用 npm、Yarn 或其他既有的套件管理工具。以下指令適用於含有 package-lock.json 的 npm 專案；其他專案請沿用原本的安裝指令。

如果儲存庫提供 Gemfile，請使用 Bundler 固定 CocoaPods 版本。沒有 Gemfile 時，才直接使用符合專案需求版本的 pod 指令；不要混用全域與專案工具鏈。

接著開啟 workspace

安裝 Pods 後，請開啟 iOS 目錄中的 .xcworkspace，不要只開啟 .xcodeproj。選擇實際使用的 scheme，並使用 Release 設定進行封存。

封存前確認版本號、建置號與簽章。封存成功後，在 Organizer 中依測試或發佈用途匯出；模擬器建置成品不能取代可安裝到裝置的套件。

重現專案環境

node --version
ruby --version
npm ci
bundle install
cd ios
bundle exec pod install

Bundler 的兩個指令以專案含有 Gemfile 為前提。安裝記錄出現錯誤時，先保留第一個錯誤及相關版本資訊，再嘗試修復。

單獨檢查 Hermes

Hermes 編譯失敗時，先確認 React Native 版本、Pods 鎖定檔、Xcode 版本與原生相依套件的相容性。如果記錄顯示找不到 Node，請檢查建置指令碼使用的 Node 路徑；不要先停用 Hermes 或刪除所有鎖定檔，這會改變專案行為與相依套件結果。

使用 Unity

移轉匯出的專案

在 Windows 繼續編輯遊戲，再透過雲端 Mac 完成 Xcode 編譯與簽章。請移轉完整的匯出目錄，不要只傳一個專案檔案。

先確認模組

確認目前的 Unity 版本與安裝方式支援在本機匯出 iOS 專案，並安裝對應的 iOS Build Support。如果本機無法匯出，請將 Unity 專案移至 Mac，再使用相同版本的編輯器建置。

匯出前確認 Bundle Identifier、指令碼後端、最低系統版本與外掛平台設定，並保存這次使用的設定。

完整傳送目錄

將匯出的 Xcode 專案連同資源、原生外掛與建置指令碼一起壓縮傳送。解壓縮後檢查目錄結構，避免漏傳隱藏設定或只傳 .xcodeproj。

如果外掛相依於 CocoaPods，請先執行所需的相依套件安裝步驟，再開啟產生的 workspace。不要直接從暫存的壓縮目錄進行建置。

分層排查錯誤

IL2CPP 或連結失敗時，先查看第一個編譯錯誤，檢查原生程式庫架構、framework 引用與外掛版本。建置成功後，再處理憑證與描述檔不相符的問題。

大型資源套件可考慮 Pro 方案，規格為 M4 Pro / 64GB / 2TB SSD；先確認資源大小與可用空間，不要只看專案名稱決定配置。

重新匯出 Unity 專案可能會覆蓋 Xcode 中的手動修改。請記錄必要設定，並將可自動化的修改納入專案建置流程，避免下次打包時重複操作。

認識這些術語

連線、硬體與簽章屬於不同層面。先了解各術語的含義，提交問題時就能少繞一段路。

實體節點
實際執行 macOS 的 Mac 硬體。所選節點的位置會影響遠端操作與檔案傳輸路徑，但不會改變專案的簽章要求。
獨享
租用期間專屬於你的實體 Mac，不是虛擬機，也不會與他人共用 CPU 與記憶體；仍須自行管理專案權限與建置憑證。
VNC
用來查看與操作遠端圖形桌面的連線方式。適合初次設定 Xcode 與檢查封存；畫面反應速度會受到本機網路與解析度影響。
self-hosted runner
部署在自行管理的機器上的 CI 執行器。建置會在這台 Mac 上執行；註冊權杖、工作權限與清理策略須由團隊設定。
統一記憶體
Apple Silicon 中由處理器與圖形運算共同使用的記憶體。專案規模、平行編譯及同時開啟的工具都會占用這部分資源。
簽章憑證
用於應用程式簽章的身分憑證，簽章時通常也需要對應的私密金鑰。只匯入憑證而沒有配對的私密金鑰，仍可能無法完成簽章。
Provisioning Profile
連結應用程式識別碼、簽章資格與發佈用途的描述檔。必須與憑證、Team、應用程式功能及匯出類型相符。
.ipa
供 iOS 裝置使用的應用程式套件。成功產生檔案不代表能安裝在任何裝置上；實際可安裝或發佈的範圍仍取決於簽章與匯出方式。

打包後再確認

除了帶走建置成品，也要安排好租期與資料。關閉遠端桌面視窗，不代表租用服務已停止。

還沒完成，如何續租？

到期前登入控制台，查看目前服務的續費入口、帳單與到期日。確認週期與金額後完成付款，再確認服務期限是否已更新。如果已提交付款但狀態尚未更新，請附上訂單編號與交易憑證提交工單；不要只憑付款截圖判斷已續租。

打包完成後，如何停止服務？

服務依天、週、月、季預付，到期未續租即停止。提前完成工作時，請先匯出檔案，再於控制台確認服務期限與可用操作。登出 VNC、關閉 SSH 或手動關機，都不能取代對訂單計費狀態的確認，也不代表會自動退款。

到期後，檔案還在嗎？

服務到期停機後，資料會依服務條款規定清除，請勿將停機後的主機當作備份磁碟。請在到期前匯出原始碼、.ipa、Archive、dSYM 與必要設定，並在本機確認檔案可讀。依團隊政策安全備份憑證與私密金鑰；確認不再使用後，請從遠端移除敏感憑證。不要假設到期後仍能重新連線或復原檔案。

續費有哪些付款方式？

僅支援 USDT-TRC20 與 Visa / Mastercard / Amex（透過 Stripe），一律以美元（USD）結算；實際可用的付款閘道以後端介面回傳為準。如有付款問題，請提供訂單編號、付款方式與交易狀態；請勿透過電子郵件或工單傳送完整卡號、安全碼、密碼或私密金鑰。

完整說明錯誤訊息

已下單的問題請透過控制台提交工單；購買前的方案選擇或暫時無法登入時，可在聯絡頁查看電子郵件聯絡方式。問題會依工單順序處理，不保證未確認的回覆時限。

提供重現條件

請寫明訂單編號、框架版本、Xcode 版本、操作步驟與失敗時間，並註明時區。建置問題請提供第一個錯誤及前後的記錄，不要只截取最後一行「失敗」。

查看聯絡方式

移除敏感資訊

請先遮蔽記錄中的密碼、權杖、私密金鑰與客戶資訊。申請可用率補償時，請另附受影響的時段；付款問題請提供交易識別碼，不要附上無關的專案原始碼。

如果遇到連線中斷，請說明 VNC 與 SSH 是否同時受到影響，以及切換本機網路後的情況，方便判斷問題出在連線還是建置。

還卡在哪個步驟？

提供訂單編號與第一個錯誤訊息，我們就從具體步驟開始排查。

提交工單