第2章：iOS SDK开发环境搭建（Xcode、Homebrew、依赖管理）

2.1 为什么要认真对待环境搭建？

环境搭建看起来是体力活，但往往是后面所有问题的根源。我最早做密码SDK时，花了两天时间排查一个链接错误，最后发现是Xcode版本和Homebrew装的工具链不匹配。所以这一章，我们一步一步把基础扎稳。

说实话，iOS SDK开发的环境并不复杂，就三个核心组件：Xcode、Homebrew和依赖管理工具。它们之间的关系可以用下面这张图概括：

iOS SDK开发环境搭建流程 iOS SDK 开发环境搭建核心组件 Xcode (App Store) IDE + 工具链 + Simulator Homebrew 包管理器 / 工具安装 依赖管理工具 CocoaPods / Carthage / SPM 目标：密码SDK编译 XCFramework / .a / .framework 小提示： Xcode 版本决定 toolchain Homebrew 帮你补全辅助工具 推荐先装 CocoaPods 再按需加 Carthage/SPM

这张图就是你未来几周工作的骨架。记住，顺序不能乱：先装Xcode，再装Homebrew，最后用Homebrew装依赖管理工具。

2.2 Xcode：绕不过的大家伙

Xcode 是iOS开发的根。它不光是一个编辑器，还绑定了编译器(clang/LLVM)、调试器(LLDB)、模拟器和各种工具链。说白了，你写的所有 Objective-C 和 Swift 代码，最后都靠它变成二进制。

2.2.1 安装与版本选择

去 Mac App Store 搜 Xcode，下载就行。但这里有个坑：你可以同时装多个 Xcode 版本吗？可以，但要注意两点：

  • 命令行工具版本：用 xcode-select -p 查看当前激活的 Xcode 路径，用 xcode-select -s /Applications/Xcode-beta.app 切换。
  • 模拟器Runtime：多版本 Xcode 共享同一套模拟器镜像，偶尔会冲突。我碰到过一次，iOS 16 的 Runtime 在 Xcode 14.3 和 15.0 之间乱掉，最后只好删掉重装。
个人习惯：我通常保留两个 Xcode——正式版和新版beta。正式版用来做日常编译和提审，beta版用来预览新API兼容性。切换时要记得重新跑一遍 sudo xcode-select --switch 并重启终端。

2.2.2 确认安装了 Command Line Tools

Xcode 自带命令行工具，但有时你只装了 Xcode.app，没装 CLI。可以手动触发：

xcode-select --install

如果系统提示「已经安装」，你就用这个命令确认路径：

xcrun --show-sdk-path --sdk iphoneos
# 正常输出类似：/Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/Developer/SDKs/iPhoneOS.sdk
千万别忽视这个：我曾经帮一个同事调试编译报错，发现他的 xcrun 根本找不到 SDK，因为他的 Xcode 是从别处拷来的，没有跑过 sudo xcodebuild -runFirstLaunch。装了 Xcode 后，一定打开一次 Xcode.app 同意协议、完成组件安装。

2.3 Homebrew：macOS 缺少的包管理器

Homebrew 是 macOS 上的瑞士军刀。你装 CocoaPods、Carthage、SwiftLint、CMake 等都靠它。没有 Homebrew，手动装这些依赖会让你崩溃。

2.3.1 安装 Homebrew

打开终端，一行搞定：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

如果网络慢，可以用国内镜像（比如中科大源）：

export HOMEBREW_BREW_GIT_REMOTE="https://mirrors.ustc.edu.cn/brew.git"
export HOMEBREW_CORE_GIT_REMOTE="https://mirrors.ustc.edu.cn/homebrew-core.git"
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
避坑指南：安装完成后务必执行 brew doctor，它会告诉你有没有权限问题或冲突。我以前图省事没跑，结果后来 brew 装东西总报「Permission denied」，查了一圈才发现是 /usr/local 目录权限被改乱了。

2.3.2 常用 Homebrew 操作

命令 说明
brew install <package> 安装软件包
brew uninstall <package> 卸载
brew list 查看已安装的包
brew upgrade <package> 升级指定包
brew update 更新 Homebrew 自身及 Formula
brew doctor 检查环境健康度

对于 SDK 开发，我默认会装这些：

brew install cocoapods
brew install swiftlint  # 代码风格检查
brew install xcbeautify # 美化编译输出日志
brew install carthage   # 如果你用 Carthage

2.4 依赖管理工具：选哪个？

iOS 生态系统里主要有三种依赖管理方式。嗯，其实还有一种叫「手动拖入」，但那是新手才干的。我们直接看对比：

特性 CocoaPods Carthage Swift Package Manager
配置文件 Podfile (Ruby DSL) Cartfile (简单文本) Package.swift (Swift)
编译方式 自动生成 workspace / 编译到 Pods/ 目录 编译为 Framework，手动拖入 集成到 Xcode，自动解析
二进制分发 支持通过 spec 配置 需自己打包或第三方服务 原生支持 binary target
Swift 友好度 中等 较高 最高（官方推荐）
项目规模 大型、多平台 中大型、模块化 中小型、纯 Swift 项目
生态成熟度 ★★★★★ ★★★★ ★★★★（仍在进化）

我个人习惯：如果做密码 SDK 需要发布给外部使用，我倾向用 CocoaPods，因为它的 spec repo 最成熟，用户只需要 pod install 就能用。如果只在团队内部测试，我会直接用 SPM——省去 Podfile 的配置成本。

一个经验：密码 SDK 通常涉及安全编译选项（如 -fstack-protector、加密链接标记），CocoaPods 的 post_install hook 可以帮你统一注入这些 flag。SPM 目前对编译选项的控制相对弱一些。所以如果你需要精细控制二进制文件的 security 属性，CocoaPods 还是首选。

2.5 环境搭建检查清单

每次我开新项目或换 Mac 时，都会过一遍下面这个清单，确保不会漏东西：

  1. Xcode：最新稳定版 + 运行过一次、同意协议、模拟器能正常启动。
  2. Command Line Tools：xcrun -show-sdk-path 有输出。
  3. Homebrew：brew doctor 返回「Your system is ready to brew」。
  4. CocoaPods：pod --version 能显示版本号。
  5. Git：Xcode 自带但最好确认 git --version 可用。
  6. 模拟器：至少装一个 iOS 17 的 Runtime (可在 Xcode -> Settings -> Platforms 下载)。
曾经有一次：我在一台新 Mac 上跑 pod install，结果卡在「Setting up CocoaPods master repo」。后来发现是我没装 Xcode 的 Command Line Tools，导致 git 的 credential helper 找不到。解决方法是先装 Xcode 并重启终端，再跑 pod setup。记住，环境变量 $PATH 必须包含 Xcode 的 bin 目录。

2.6 小结：下一步就开工了

← 上一章 📖 返回目录 下一章 →