React Native 如何在 Mac 上開發 iOS App？從 Node.js、CocoaPods 到 Xcode 編譯

遇到 JavaScript 已能執行、iOS 卻卡在原生建置或 CocoaPods 的錯誤？
最快的處理方式是依序核對專案指定的 Node.js 與套件、Xcode 工具鏈、CocoaPods，再啟動模擬器或以 Xcode 編譯；版本與命令以專案設定和官方文件為準。

適合剛開始用 React Native 建置 iOS App、需要從頭準備 Mac 環境的開發者。
已能撰寫 React Native 程式，卻卡在 CocoaPods 或 iOS 原生依賴的前端工程師，也可按流程定位問題。
若團隊需要在本地或遠端 Mac 執行模擬器、建置 iOS App，本文的核對步驟同樣適用。

先按實際建置流程確認環境

React Native 可以在 Mac 上開發 iOS App，但工作流程不只是安裝 JavaScript 套件：專案依賴、原生 iOS 依賴、Xcode 工具鏈與模擬器各有自己的檢查點。React Native 官方環境指南涵蓋 iOS 開發所需的 Mac 與 Xcode 準備；實際版本和指令仍要回到專案文件核對。React Native 官方環境設定指南

階段	開工前核對	可查看的專案資料或結果
Node.js 與 JavaScript 套件	使用專案指定的 Node.js 與套件管理工具；安裝方式要與鎖定檔一致	package.json 的 engines、packageManager、scripts，以及套件鎖定檔；npm 的 package.json 說明列出可用欄位。查看 npm 文件
Xcode 與模擬器	確認 Xcode 可開啟，命令列工具選擇正確，所需模擬器元件可用	Xcode 顯示的版本、目前選取的命令列工具與可選模擬器；Apple 說明命令列工具的安裝與使用方式。查看 Apple 說明
CocoaPods 與 iOS 原生依賴	先確認專案是否使用 CocoaPods，以及專案要求的執行方式	Podfile、Podfile.lock、Pods 目錄與 Xcode 工作區；CocoaPods 的 Podfile 指南說明 Podfile 用於描述專案依賴。查看 Podfile 指南

這些檢查項能提供實際可比對的資料：Node.js 版本來自專案設定與執行結果，原生依賴版本可在 Podfile.lock 核對，Xcode 工具與模擬器則以當前環境顯示的內容為準。不要用另一個專案的版本號代替目前專案的相容條件。

先依專案設定安裝 Node.js 與 JavaScript 依賴

Node.js 版本沒有適用所有 React Native 專案的固定答案。先開啟 package.json，查看是否聲明 engines 或套件管理工具，再檢查專案說明和鎖定檔；若設定彼此不一致，先查團隊文件或建置流程，不要直接升級 Node.js 或重建鎖定檔。

選定工具後，再使用該工具對應的安裝方式。例如，專案明確採用 npm 並提交 npm 鎖定檔時，依專案文件選擇安裝命令；npm 文件說明 npm install 的安裝行為與套件設定。npm 安裝指令說明 安裝完成後，可執行 node --version 與相應套件管理工具的版本指令，並以專案指定的啟動或測試指令驗證依賴是否可用。

留意同一份程式碼若以不同套件管理工具安裝，可能得到不一致的依賴狀態。不要只因安裝指令成功，就認定 iOS 原生依賴也已安裝。

再核對 Xcode、命令列工具與模擬器

開啟 Xcode 完成初始設定，接受所需授權，並確認命令列工具指向目前打算使用的 Xcode。可用 xcodebuild -version 查看命令列工具回報的版本，使用 xcode-select -p 確認目前選擇的開發者目錄；若顯示路徑或版本與預期不同，先處理工具選擇問題，再跑原生建置。Apple 的命令列工具文件可用來核對相關設定方式。Apple 命令列工具說明

接著在 Xcode 查看是否有專案需要的 iOS 模擬器元件。可用元件會受目前 macOS、Xcode 及已安裝元件影響；不要只憑網路上的截圖推斷本機一定有相同選項。Apple 提供了額外 Xcode 元件的下載與安裝說明，可用來處理模擬器元件未就緒的情況。查看 Xcode 附加元件說明

如果目標是安裝到實體裝置或分發 App，還要另行確認簽署與裝置註冊設定；這不是模擬器成功啟動就會自動完成的步驟。Apple 的 Xcode 裝置分發文件說明了註冊裝置與分發流程。Apple 裝置分發說明

再安裝 CocoaPods，核對原生依賴是否一致

先進入專案含有 Podfile 的目錄，確認 README、Gemfile 或建置文件指定的 CocoaPods 安裝與執行方式。專案若透過 Bundler 管理 CocoaPods，按專案規範使用 Bundler；否則才依專案說明使用 CocoaPods 指令。不要把某個專案可用的安裝方式當成所有專案的通則。

Podfile 描述要整合的原生依賴；pod install 依照既有設定安裝依賴，結果會反映在 Pods 相關檔案與 Podfile.lock 中。CocoaPods 也明確區分 pod install 與 pod update：後者涉及更新依賴，不能為了消除建置錯誤就隨意取代前者。CocoaPods 對照 pod install 與 pod update

安裝後依專案產生的檔案開啟 Xcode。若專案使用 CocoaPods，通常應開啟整合後的 .xcworkspace；直接開啟 .xcodeproj 可能讓工作區沒有載入 Pods 整合。檢查 Podfile.lock 是否符合專案預期、安裝輸出是否有錯誤，再開始編譯。

用清單驗證模擬器與原生編譯

React Native iOS 開發要分清 Metro 與 Xcode 建置：Metro 提供 JavaScript 開發流程，模擬器啟動或 Xcode 建置則會走 iOS 原生工具鏈。官方模擬器指南說明如何在 iOS 模擬器執行 React Native App；專案 scripts 的實際名稱則要以 package.json 為準。React Native iOS 模擬器指南

• [ ] 確認 Node.js 版本符合專案設定，且採用專案指定的套件管理工具。
• [ ] 依鎖定檔與專案指示安裝 JavaScript 依賴，確認相關啟動 scripts 存在。
• [ ] 確認 Xcode 可用、命令列工具選擇正確，並能選取所需模擬器。
• [ ] 依專案文件安裝 CocoaPods 依賴，檢查 Podfile.lock 與安裝輸出。
• [ ] 依專案指令啟動 iOS App，並分別查看 Metro 輸出與 Xcode 原生建置記錄。
• [ ] 若編譯成功，再確認 App 是否能在指定模擬器啟動；若需實體裝置，另查簽署設定。

觀察到的結果	優先檢查	下一步
JavaScript 套件找不到或啟動指令失敗	Node.js 版本、套件管理工具、package.json 與鎖定檔	按專案文件重裝依賴，再執行專案指定的驗證指令
原生模組或 Pods 缺失	Podfile 位置、CocoaPods 執行結果、Podfile.lock	確認在正確目錄安裝，並使用已整合 Pods 的工作區
Xcode 找不到 SDK、工具或模擬器	命令列工具選擇、Xcode 元件與模擬器清單	修正目前工具選擇，按 Apple 文件安裝所需元件
錯誤發生於簽署或裝置安裝	Xcode 目標設定、簽署資料及裝置註冊	依目標是模擬器、測試裝置或分發建置分別核對設定

依建置日誌定位錯誤，不先套用清除指令

先看第一個真正的錯誤，而不是只看最後一行「Build failed」。若依賴解析或 JavaScript 啟動階段失敗，回到 Node.js、套件設定和鎖定檔；若錯誤指出 Pod、原生模組或工作區設定，查看 CocoaPods 安裝輸出與 Podfile.lock；若訊息指向 SDK、編譯器或模擬器，核對 Xcode 工具選擇與元件。

錯誤出現在簽署、佈建或裝置安裝階段時，再檢查 Xcode 專案的簽署設定與裝置條件。不同階段需要不同證據，刪除依賴目錄或更新 Pods 不保證能解決問題；尤其在多人協作專案中，未經確認更新原生依賴，可能改變鎖定的依賴狀態。

常見問題

React Native iOS App 開發前，Mac 上需要哪些環境？

需要能執行 macOS 與 Xcode 的 Mac，並按專案設定準備 Node.js、JavaScript 套件和 iOS 原生依賴。是否需要 CocoaPods、使用哪種套件管理工具，都應由專案文件、package.json、鎖定檔與 Podfile 判斷。最後確認 Xcode 命令列工具和所需模擬器可用；只安裝 Node.js 並不足以完成 iOS 原生建置。

CocoaPods 依賴要怎樣安裝才不會改動專案預期？

從含有 Podfile 的專案目錄開始，先閱讀專案文件與 Gemfile，依指定方式執行安裝。CocoaPods 文件指出 pod install 與 pod update 用途不同；需要維持現有依賴鎖定時，不應任意改用更新操作。完成後檢查安裝輸出、Podfile.lock 與工作區，再從整合 Pods 的工作區開啟 Xcode。

Xcode 如何執行 React Native iOS 模擬器？

先安裝專案 JavaScript 依賴，確認 Xcode 與所需模擬器已可用，再按 package.json 中的專案指令啟動 iOS App，或開啟工作區並選取模擬器建置。檢查時分開看 Metro 與 Xcode 的輸出：前者用於 JavaScript 開發流程，後者顯示原生編譯結果。若模擬器元件不存在，先核對 Xcode 元件，而非改動應用程式依賴。

iOS 編譯失敗時，第一步應該看什麼？

看建置日誌中最早出現的具體錯誤，以及它屬於哪個階段。依賴解析問題先核對 Node.js、套件管理工具和鎖定檔；Pods 或原生模組問題查看 Podfile、安裝輸出與工作區；SDK 或模擬器問題檢查 Xcode 工具選擇與已安裝元件。只有錯誤指向簽署或裝置安裝時，才優先追查簽署與註冊設定。

若目前使用的環境不是 Mac，或團隊共用的 Mac 無法穩定用於模擬器與原生編譯，繼續在不支援 Xcode 的環境反覆調整，無法取代實際的 macOS 建置流程；臨時借用設備也可能受可用時間與環境不一致影響。需要短期建置或測試環境時，可先查看 Zutcloud 的 Mac mini 租用資訊，再按專案需求評估遠端 Mac；若長期持續高負載，或必須連接實體週邊，則應比較自有 Mac 是否更合適。租用前亦可先核對 Mac mini 方案與價格資料，並確認方案條件能否滿足專案的 Xcode 與裝置需求。