Mac 從零搭建 iOS 開發環境：Xcode、Homebrew、Git、CocoaPods 到第一個 App 完整教學

先安裝並啟動 Xcode，再設定 Homebrew 與 Git；只有專案依賴明確要求時才安裝 CocoaPods。最後用 Xcode 建立 iOS App，在模擬器或適用的實體裝置上完成建置與啟動驗證。

這套流程適合第一次用 Mac 學 iOS 開發、需要重裝或遷移工具的開發者，以及要在本機或遠端 Mac 驗證專案的個人與團隊。本週先核對 macOS 與 Xcode 相容性，再按「Xcode → Homebrew／Git → 專案依賴 → 首次執行」逐段完成；每一步保留驗證結果，方便定位失敗點。

Mac 從零搭建 iOS 開發環境：先確認條件，再決定工具

安裝之前，先確認目前使用的 Mac 能否支援你打算安裝的 Xcode。Apple 會在系統要求頁列出各 Xcode 版本支援的 macOS 範圍；不要只看 macOS 名稱或「最新版本」字樣，應以你要用的 Xcode 版本對照官方系統要求表。若專案指定了 Xcode 版本，也要先確認它和目前系統相容。

取得 Xcode 可從 Apple 提供的官方下載資源開始，並留意你選取的版本對 macOS 的要求。Apple 帳號不應被當成所有入門情境的硬性門檻：如果你目前只在模擬器執行範例，可先完成本機建置；要在裝置上測試或使用帳號相關服務時，再按Apple Developer 帳號說明確認所需條件。

工具分工：哪些現在要裝，哪些按專案決定

先分清楚每個工具的工作，再開始安裝。Xcode 提供 iOS 開發與建置所需的 SDK、工具及模擬器；Homebrew 管理額外的命令列套件；Git 管理版本變更；CocoaPods 則只處理採用它的專案依賴。後三者都不是 Xcode 的替代品。

決策條件：依專案選擇依賴工具

• 若專案提供 Podfile，或維護文件明確要求 CocoaPods，就按該專案的說明安裝並使用 CocoaPods。
• 若專案使用 Swift Package Manager，或 Xcode 專案已直接管理所需套件，就沿用現有方式，不要額外引入 CocoaPods。
• 若你正在建立全新的空白 App，而且沒有外部依賴，先不裝 CocoaPods；需要時再按官方加入 Xcode 套件依賴的說明選擇適合的管理方式。

這個分支能避免一種常見的環境負擔：為了「工具裝得齊」先安裝依賴管理器，結果增加 Ruby、套件版本與專案設定等另一組問題，卻沒有實際依賴需要處理。

第一階段：安裝並初始化 Xcode

先完成 Xcode，再處理其他工具。這樣做能先確認 Mac 的 iOS SDK 與基本建置環境正常，也讓後續檢查 Git 或 CocoaPods 時，不會把 Xcode 工具缺失誤認成套件安裝問題。

1. 選擇符合 macOS 的 Xcode 版本。 查看 Apple 系統要求頁，若是替既有專案重建環境，也先核對團隊要求的 Xcode 版本。
2. 從官方渠道取得 Xcode。 安裝完成後首次開啟，依畫面提示完成必要元件安裝與授權流程。不同版本顯示的選項可能有差異，按當前畫面與 Apple 說明操作。
3. 確認命令列工具是否就緒。 在終端機執行 xcode-select -p。它會顯示目前選取的開發者目錄；再執行 xcodebuild -version，確認命令可以回報 Xcode 版本資訊。
4. 處理缺少的元件或授權提示。 若 Xcode 命令無法執行，先回到 Xcode 首次啟動流程，檢查是否仍有元件待安裝。Apple 也提供安裝額外 Xcode 元件的說明與命令列工具文件；依錯誤訊息確認問題屬於元件、工具路徑還是授權，而不是先重複安裝整個環境。
5. 建立一個基本 iOS 專案。 之後用它做一次建置與模擬器執行，確認 Xcode 不只安裝成功，亦能實際完成開發流程。

若你正在公司管理的 Mac 上操作，先確認組織允許安裝開發工具及模擬器元件。管理政策造成的權限錯誤，應由裝置管理者處理，與 Xcode 本身是否可用是不同問題。

第二階段：設定 Homebrew 與 Git

依官方指引安裝 Homebrew

Homebrew 的安裝方式與環境要求應以官方安裝文件為準。先閱讀當前文件，再執行其中提供的安裝指令；不要從不明教學複製腳本，也不要因安裝遇到錯誤就連續貼上多組修復命令。

完成後，執行：

brew --version

若終端機回報找不到 brew，先檢查官方文件中的安裝完成後設定步驟，以及目前終端機使用的 shell 環境。不要假設 Xcode 安裝失敗，也不要在未看錯誤內容前自行改動路徑。Homebrew 只是套件管理工具；若當前專案沒有需要透過它安裝的額外命令列工具，你可先完成 Xcode 與 Git 驗證，再決定是否使用它。

確認 Git，並設定提交身分

macOS 上的 Git 可透過 Xcode 命令列工具取得，也可依Git 官方 macOS 安裝說明選擇合適來源。先執行：

git --version

若能回報版本資訊，先確認目前 Git 已可用，不需要為了「再裝一份」增加工具來源。若找不到 Git，檢查命令列工具是否完成安裝，再按官方文件處理。

Git 提交需要能識別提交者的姓名與電郵。設定前請使用你希望出現在提交記錄中的資料：

git config --global user.name "你的姓名"
git config --global user.email "你的電郵"
git config --global --list

--global 會將設定套用到目前使用者的 Git 環境；如果團隊要求不同的專案身分，可以改用專案層級設定。檢查輸出時，確認名稱及電郵沒有拼錯，也沒有把不應公開的私人資料意外寫入公開提交記錄。

第三階段：按需安裝 CocoaPods，並檢查依賴

先查看專案根目錄及維護文件。若存在 Podfile，或專案明確要求 CocoaPods，才依CocoaPods 官方入門指南安裝。安裝方式可能受目前 Ruby 與專案環境影響，因此按官方文件及團隊既有設定選擇，不要把某一條固定安裝命令視為所有 Mac 都適用。

在專案目錄依文件執行依賴安裝後，檢查下列結果：

• pod --version 能否執行，確認 CocoaPods 命令可用。
• 專案是否已有 Podfile，以及依賴安裝是否回報錯誤。
• 是否產生或更新預期的 workspace 與鎖定檔。
• 開啟專案時，是否使用專案文件要求的 Xcode 專案或 workspace。

若 CocoaPods 安裝失敗，先辨認錯誤發生在 Ruby 環境、套件安裝權限，還是專案依賴解析。若安裝完成但 Xcode 無法建置，檢查依賴版本與專案要求，再回頭查看 Xcode 相容性。不要在尚未確認原因時刪除鎖定檔，否則可能改變團隊已確認的依賴版本。

第四階段：建立並執行第一個 iOS App

使用 Xcode 的新專案流程建立 iOS App。Apple 的建立 App 專案文件可對照目前介面。選擇 iOS App 類型，並按你的目的填入名稱、組織識別資訊及其他必要欄位。範本決定初始專案結構；若只是驗證環境，先使用簡單的預設 App 專案，避免一開始就加入不必要的套件與自訂設定。

建立後先核對專案設定，再執行：

1. 在 Xcode 開啟剛建立的專案，確認左側檔案清單與專案設定正常顯示。
2. 在執行目標選單選擇目前可用的 iOS 模擬器。若目標清單沒有合適項目，檢查相應模擬器元件是否已安裝。
3. 按下建置與執行。先看 Xcode 的建置結果；出現錯誤時，從第一條相關錯誤讀起，不要只根據最後一行判斷。
4. 等待模擬器啟動並確認 App 畫面出現。這是環境可用的重要證據：工具能建置，產出的 App 也能在選定目標上啟動。
5. 要改用實體裝置時，確認裝置連線、簽署設定與 Apple 帳號條件。Apple 帳號與裝置測試需求會因用途而異，不應把模擬器入門與實體裝置部署混為一談。

第五階段：按順序排查首次執行問題

不要一出錯就重裝所有工具。按流程定位，能把問題限制在安裝、依賴、建置或啟動其中一段。

• [ ] 安裝： Xcode 已啟動，xcode-select -p 與 xcodebuild -version 都能回應。若不行，先檢查 Xcode 元件、工具路徑及授權提示。
• [ ] 套件： brew --version 能確認 Homebrew；若專案使用 CocoaPods，pod --version 亦能執行。若命令不存在，先檢查安裝步驟與目前終端機環境。
• [ ] 依賴： 專案採用的依賴管理方式與 README 一致。依賴解析出錯時，查看套件來源、版本要求及鎖定檔，不要先混用管理工具。
• [ ] 建置： Xcode 的建置結果沒有未處理錯誤。若失敗，從最早出現、與專案程式碼或依賴相關的錯誤開始查看。
• [ ] 啟動： 已選擇有效的模擬器或適用的實體裝置，並確認 App 實際出現。只看到建置成功，不等於已完成執行驗證。

常見問題

Mac 從零搭建 iOS 開發環境時，Xcode 要先做甚麼？
先核對 macOS 與 Xcode 的相容要求，再從 Apple 官方渠道取得並首次啟動 Xcode。完成必要元件與授權流程後，以 xcode-select -p 和 xcodebuild -version 檢查命令列工具。遇到問題時先定位元件、工具路徑或授權，不要直接重裝所有開發工具。

Homebrew 和 Git 要不要一起安裝？
兩者職責不同：Homebrew 管理額外命令列套件，Git 管理程式碼版本。先用 git --version 看 Git 是否已可用，然後設定提交姓名與電郵；只有你要用 Homebrew 管理套件時，才按其官方文件完成安裝與驗證。這些工具都不能取代 Xcode 的 iOS 建置能力。

甚麼專案才需要 CocoaPods？
以專案的依賴文件為準。看到 Podfile 或維護文件要求 CocoaPods，才按官方指南安裝並執行依賴解析；若專案採用 Swift Package Manager，或沒有外部依賴，便沿用現有方式。這可避免額外引入不必要的 Ruby、套件版本與專案設定問題。

怎樣確認第一個 App 真的能運作？
在 Xcode 建立 iOS App，選擇可用模擬器，先確認建置成功，再執行並看到 App 畫面。建置結果與模擬器啟動畫面分別證明編譯和啟動流程可用。若改用實體裝置，另行檢查裝置連線、簽署設定與專案所需的帳號條件。

完成後，先按清單確認 Xcode、套件依賴、建置與 App 啟動結果，保留錯誤訊息和成功的執行目標，日後重裝或交接時更容易復現。若你已有合適的本機 Mac，持續使用它通常較直接；若目前設備不適合安裝 Xcode，或團隊需要共用測試環境，本機方案會受設備可用性、權限與維護責任限制，遠端操作則要考慮網路連線與互動延遲。可先查看 Hashvps 的方案資料，逐項比對是否具備本文所需的 Xcode 安裝、建置及執行條件；有操作疑問時，再參考 Hashvps 說明中心。