Mac 从零搭建 iOS 开发环境：Xcode、Homebrew、Git、CocoaPods 到第一个 App 完整教程

症状：Xcode 已经装好，却不知道 Git、依赖工具和模拟器还差哪一步。

最快做法：Mac 从零搭建 iOS 开发环境时，本周按“先确认 Mac 条件，再安装并启动 Xcode，接着配置 Homebrew 和 Git，最后按项目要求决定是否安装 CocoaPods”的顺序完成。新建 iOS 项目并在模拟器或适用的实体设备上成功启动，才算验证通过。

谁该看这篇：第一次用 Mac 学 iOS、需要重装或迁移开发工具，或需要在本机及远程 Mac 上完成构建验证的你。

Mac 从零搭建 iOS 开发环境：先检查 Mac 条件，再安装工具

先确认 macOS 版本、芯片类型、可用存储空间和当前账号权限。点击苹果菜单中的“关于本机”查看系统版本和芯片信息；在“系统设置”中检查存储空间。Xcode、平台组件和模拟器运行时都会占用空间，具体需要多少取决于你要安装的平台、组件和项目体量，不要把网上的固定容量当作所有设备的要求。

Xcode 与 macOS 的兼容范围会随版本变动。安装前对照 Apple 的 Xcode 系统要求表，不要只看 Mac 是否能打开安装包。还要核对团队项目指定的 Xcode 版本和目标系统范围，避免新装的工具与现有工程不匹配。

Homebrew 的系统要求可能变化，安装前请查看官方安装要求。公司管理的 Mac 若限制写入或需要管理员授权，先确认账号权限和设备管理策略；安装失败时不要直接反复尝试 sudo。

Apple 账号不是每一步都必需。只在模拟器中验证时，可以先不绑定实体设备；若要在自己的设备上安装测试应用，再在 Xcode 中登录并处理相应签名设置。免费个人团队的设备配置有期限限制，也不等同于应用发布资格。(Apple Developer：开发者账号说明)

Xcode 先装完整：再确认 SDK、模拟器和命令行工具

从 Apple 的 Xcode 官方页面进入 Mac App Store 下载，或按项目要求从 Apple 提供的下载入口选择版本。首次打开 Xcode 时，按提示完成初始化并安装需要的平台组件。Xcode 提供 iOS SDK、代码编辑、构建调试工具和模拟器；单独安装命令行工具并不等于装好了完整的 iOS 图形开发环境。

操作时按这个顺序检查：

1. 打开 Xcode，等待首次设置完成。若出现许可或组件安装提示，按界面完成；在下载结束前，不要把“项目能创建”误判为“项目能构建”。
2. 打开 Xcode 的平台或组件设置，确认所需的 iOS 支持和模拟器运行时已安装。缺少对应平台支持时，项目可能可以创建，却不能构建或运行；按 Apple 的组件安装说明补齐所需内容。
3. 打开终端运行 xcode-select -p，检查当前命令行开发目录；再运行 xcodebuild -version，确认完整 Xcode 提供的构建工具可用。
4. 若终端提示未选择开发者目录，先在 Xcode 设置中选择当前安装的 Xcode，再回到终端复查。若许可或首次启动组件导致命令无法继续，回到 Xcode 按提示完成初始化，不要在路径未确认时盲目卸载或重装工具。
5. 如果只需要 Git 等部分终端工具，可以了解 Apple 对 Xcode 命令行工具的说明；但创建 iOS 项目、管理模拟器或使用完整构建链路，仍应先安装并启动完整 Xcode。

Homebrew 管软件，Git 管代码：分开配置更容易定位问题

Homebrew 用来安装和维护命令行软件；Git 用来记录代码变更。Homebrew 不是 Xcode 的替代品，Git 也不会提供 iOS SDK 或模拟器。先安装并启动完整 Xcode，再检查 Git，可以避免重复安装。

安装并验证 Homebrew：

1. 从 Homebrew 官方安装文档进入安装入口，先阅读安装程序将执行的操作，再决定是否确认。不要从论坛复制来源不明的命令。
2. 按安装程序最后给出的提示配置 shell 环境。若新开终端后找不到 brew，检查当前 shell 配置文件是否加入安装器建议的 brew shellenv，再重新打开终端。
3. 运行 brew --version 验证命令可用；如需进一步排查，再运行 brew doctor，根据报告检查路径或权限问题。漏掉 shell 环境配置时，安装看似完成，终端仍可能找不到命令。

检查并设置 Git：

先运行 git --version。若系统提示安装开发者工具，按提示完成后再检查；Xcode 命令行工具已包含 Git 时，不必重复安装。若项目或团队要求另一版本，再按照官方 Git 安装说明选择合适方式。

Git 可运行后，设置提交身份：

git config --global user.name "你的姓名"
git config --global user.email "你的邮箱"
git config --list --show-origin

姓名和邮箱会写入提交记录。全局设置会作用于这台 Mac 上的项目；团队若要求项目级身份，可进入项目目录后改用 --local。检查配置来源还能帮助你发现旧设置覆盖新配置的情况。

CocoaPods 按项目决定：先看依赖文件，再选工具

开始前先读项目说明和依赖文件。若仓库采用 Xcode 内置的 Swift Package Manager，就在 Xcode 中解析并检查依赖；Apple 说明，Xcode 可添加 Swift 包，并通过 Package.resolved 记录解析结果。(Apple：向 App 添加包依赖)

若项目已有 Podfile，且团队要求 CocoaPods，再按 CocoaPods 官方入门文档安装。官方建议使用独立管理的 Ruby 环境，而不是长期依赖系统 Ruby。不要因为某条网上命令带 sudo 就直接照抄；先确认 Ruby 路径和权限，再依项目要求处理。

在 Podfile 所在目录运行：

pod install

检查是否生成或更新 Pods 目录、Podfile.lock 和项目工作区，再按项目说明打开对应工作区构建。不要随意删除锁定文件或更换依赖管理方式；迁移项目时，先按团队文档核对依赖工具和锁定文件。

按条件选择：

• 若项目有 Podfile，且构建说明要求 CocoaPods，就安装并按仓库流程解析依赖。
• 若项目使用 Swift Package Manager，且没有 CocoaPods 配置，就用 Xcode 管理 Swift 包，不额外添加 CocoaPods。
• 若仓库没有依赖声明，或你尚未确认团队做法，就先看 README、锁定文件和构建说明，不要为了“凑齐工具”而安装。
• 若迁移后依赖解析失败，先核对工具版本、锁定文件和项目要求，再处理报错；不要先删锁定文件或更换管理方式。

FAQ：安装与首次运行时最容易混淆的地方

Xcode 下载后，怎样确认初始化完成？

首次打开后，等平台组件安装结束，并在终端检查 xcode-select -p 是否指向预期的 Xcode。再确认 iOS 模拟器运行时可用，创建空白项目并成功构建、启动。若构建提示缺少平台支持，先安装对应组件；若终端找不到工具，再检查活动开发目录和首次启动提示。

Homebrew 和 Git 都要单独安装吗？

不一定。Xcode 的命令行工具可能已经提供 Git，因此先运行 git --version，避免重复安装。Homebrew 管理命令行软件，Git 管理版本记录，两者职责不同。无论 Git 从哪里安装，都应设置提交姓名和邮箱，并检查配置来源，尤其是迁移过来的 Mac。

CocoaPods 是每个 iOS App 都必需的吗？

不是。先查看项目依赖文件和团队说明：有 Podfile 且项目要求 CocoaPods，才按要求安装并运行 pod install；如果使用 Swift Package Manager，就在 Xcode 中解析依赖。新项目没有外部依赖时，不需要为了完成环境搭建而预装 CocoaPods。

第一个 App 怎么运行，什么时候需要 Apple 账号？

在 Xcode 创建 iOS 项目，选择已安装的模拟器作为运行目标，点击运行，并确认模拟器里出现应用。这个过程能验证基础构建链路。若想把 App 安装到自己的 iPhone 上，再登录 Apple 账号并处理签名；仅用模拟器学习时，不必先连接实体设备。

新建并运行首个 App：用构建结果和启动画面验收

1. 打开 Xcode，选择新建项目，再选择 iOS 平台下的 App 模板。SwiftUI 是一种可选的界面技术；如果团队要求 UIKit 或其他模板，按项目标准选择，不要为了跟随教程改变工程结构。(Apple：创建 Xcode App 项目)
2. 填写产品名称和组织标识。组织标识会参与生成应用的 Bundle Identifier；团队有命名约定时优先遵守，避免后续更改带来签名或配置差异。
3. 在运行目标中选择已安装的 iOS 模拟器。若列表中没有合适目标，回到 Xcode 组件设置下载相应运行时；下载完成前，不要把“已选中目标”当作运行成功。
4. 点击运行，观察构建阶段和模拟器启动结果。通过标准不是没有红色报错，而是构建完成、模拟器启动并显示应用界面。
5. 若要在实体设备上运行，在 Xcode 中登录 Apple 账号并检查目标的签名设置；若只是验证项目模板和本机构建，先用模拟器排除设备连接与签名等额外变量。
6. 如果项目需要依赖，确认依赖解析成功后再构建。使用 CocoaPods 的工程按项目说明打开对应工作区；使用 Swift Package Manager 的工程则确认 Xcode 完成解析，并检查团队要求跟踪的 Package.resolved。

最后核对：按失败环节逐层排查

✅ 安装层：Xcode 能打开，首次设置结束；macOS 与 Xcode 版本匹配；需要的 iOS 组件和模拟器已安装。
✅ 命令层：xcode-select -p 指向预期目录；xcodebuild -version 可执行；brew --version 和 git --version 有输出。
✅ 依赖层：先确认工程采用 CocoaPods 还是 Swift Package Manager，再检查解析结果、锁定文件和项目要求。
✅ 构建层：检查 Xcode 选择的 Scheme、运行目标、平台组件和具体错误；先处理最早出现的构建错误，不要同时改多项配置。
✅ 启动层：确认模拟器运行时已安装，App 确实启动；真机失败时，再单独检查连接、账号与签名。

需要在远程 Mac 上操作时，也按同一顺序检查：macOS 是否满足 Xcode 要求、空间是否足够安装工具和模拟器、远程桌面是否能正常交互，以及项目依赖是否可访问。连接方式和机器信息以实际交付为准；你可以先查看 Hashvps 帮助中心的连接说明，并在选择前核对 Hashvps 套餐详情所列条件。远程环境不能替你完成项目依赖核验，也不能替代实体设备测试。

如果你目前借用他人的 Mac、反复迁移本机工具或临时拼装环境，常见代价是 Xcode 版本难统一、依赖与权限状态难复现、模拟器下载和本地存储受限。若只需临时构建或验证，租用 Mac 可能比为短期任务购置设备更合适；但若需要长期稳定重负载，或必须连接本地实体设备，应先判断自购 Mac 或本地环境是否更匹配。需要临时远程环境时，可先核对 Hashvps 的实际交付条件，再按本文清单确认能否完成你的安装、依赖解析、构建和运行验证。