3. Xcode 基本配置与项目创建
说实话，很多新手拿到 Xcode 第一件事就是点「Create a new Xcode project」，接着一路 Next。结果编译时各种报错，传包时又发现签名不对。嗯，我这里花点时间，把最基本但最关键的几个配置讲清楚。你想象一下，地基没打好，后面盖多少层都得塌。
3.1 Xcode 安装与版本选择
去 Mac App Store 下载，或者从 Apple Developer 官网拿 dmg。我个人习惯用官网版，因为可以保留多个版本。为什么？
我经常需要同时维护旧项目和新项目。旧项目用 Xcode 13，新项目用 Xcode 15。如果你只装一个，哪天升级后发现第三方库不兼容，你就只能哭了。
这里有个要点：Xcode 的版本必须对应 macOS 版本。比如 Xcode 15 要求 macOS Ventura 以上。安装前看一眼你的系统版本。
| Xcode 版本 | 最低 macOS | 推荐场景 |
|---|---|---|
| Xcode 13.x | macOS Big Sur 11.3 | 维护老项目，兼容 iOS 14 以下 |
| Xcode 14.x | macOS Monterey 12.5 | 主流开发，Swift 5.7+ |
| Xcode 15.x | macOS Ventura 13.5 | 新项目，Swift 5.9+，Vision Pro 支持 |
安装完成后，打开 Xcode 第一件事是什么？不是新建项目，而是检查 Preferences → Locations → Command Line Tools。我见过太多同事这里没选对，导致终端里的 xcodebuild 找不到。选对版本，比如 Xcode 15.0 (15A240d)。
3.2 Xcode 偏好设置：必须动的那几项
Preferences 里一堆选项，但真正影响编译流程的就这几个：
- Accounts：添加你的 Apple ID。不添加没法签名，没法真机调试。
- Locations → Derived Data：默认在 ~/Library/Developer/Xcode/DerivedData。我建议放到一个单独的目录，比如
~/XcodeDerivedData。为什么？方便清理。有一次我项目编译突然变慢，进去一看派生数据占了几十GB。删掉重建就好了。 - Source Control → Enable Source Control：如果你们使用 git，保持开启。如果不用，可以关掉，省得每次打开项目都刷一遍。
曾经有个同事把 Derived Data 放在了 iCloud Drive 里，结果编译时一直卡住。为什么？iCloud 同步导致文件锁冲突。千万不要把构建缓存放在云同步目录里。
3.3 创建项目：选模板那点事儿
新建项目时，Xcode 会弹出一堆模板。别急着选「App」，先想想你的目标：
- App：标准的 iOS/tvOS/watchOS 应用，带 SwiftUI 或 Storyboard。
- Framework & Library：如果你要编译一个 SDK，选它。我这次课程后面会专门讲如何创建 SDK 项目。
- Other → Empty：适合有经验的开发者，从零搭项目结构。
我习惯直接选 App，然后取消勾选「Include Tests」，因为测试目标的结构我自己单独配。勾了反而多出一堆没用的 target，编译时还多跑一遍。
3.4 项目配置：Info.plist 和 Build Settings
项目创建后，你会看到一堆配置。很多人不敢动，其实核心就这几个：
| 配置项 | 位置 | 说明 |
|---|---|---|
| Bundle Identifier | General → Identity | 唯一标识，建议用反域名，比如 com.yourcompany.sdkdemo |
| Team | Signing & Capabilities | 选择你的 Apple 开发团队，用于签名 |
| Deployment Target | General → Deployment Info | 最低支持版本。我一般选当前主流版本减一，比如现在选 iOS 16.0 |
| Build System | File → Project Settings | 一定选 New Build System (默认就是)。不要用 Legacy |
Build Settings 里我特别关注 ENABLE_USER_SCRIPT_SANDBOXING。Xcode 15 开始默认开启了用户脚本沙盒，如果你的构建过程用到了 shell 脚本（比如 CocoaPods 的 embed frameworks 脚本），可能会报错。我一般直接设为 NO。
核心原则：Info.plist 里存放的是应用元数据（版本号、权限声明等）；Build Settings 里存放的是编译行为（优化等级、架构等）。两者不要搞混。
3.5 让编译「看得见」：调试日志与构建配置
SDK 编译最头疼的就是报错找不到原因。我建议一开始就开启详细日志：
// 在终端中执行
defaults write com.apple.dt.Xcode ShowBuildOperationDuration YES
这样编译时 Xcode 会显示每个阶段耗时，方便你定位瓶颈。另外，在 Xcode 菜单栏 → Product → Scheme → Edit Scheme 里，把 Build Configuration 从 Debug 切到 Release，再点 Archive，就能看到真实打包环境下的编译结果。
为什么要分 Debug 和 Release？因为 Debug 默认带调试符号、不做优化，编译快但体积大；Release 做优化、剥离符号，适合发布。我碰到过一个案例：Debug 下跑得好好的，Release 下就闪退，最后发现是编译器优化把某个局部变量优化掉了。嗯，所以一定要两个模式都测一遍。
3.6 项目创建后的「首跑」清单
项目建完，别急着写代码。走一遍这个清单，能省你后面一堆麻烦：
- 检查 Bundle Identifier 是否正确。
- 确认 Team 已选，自动签名打勾。
- 检查 Deployment Target 是否匹配你的测试设备系统版本。
- 打开 Build Settings，搜索
EXCLUDED_ARCHS，确保没有误排除 arm64。 - 在 General → Frameworks, Libraries, and Embedded Content 里，确认不需要的依赖已被移除。
我每次建新项目都会跑一遍 Cmd + B 看看能不能编译通过。如果第一次就红，多半是签名问题——去 TARGETS → Signing & Capabilities 重新勾一下「Automatically manage signing」就行。
3.7 知识体系图：Xcode 配置与项目创建要点
下面的 SVG 图把本章的核心逻辑串起来了。箭头方向代表依赖或流程关系。
3.8 避坑总结
最后，我把这些年踩过的坑列个清单：
- 签名不一致：真机调试时突然提示
Failed to code sign，多半是你改了 Bundle Identifier 却没更新 Provisioning Profile。去 Signing & Capabilities 重新点一下「Automatically manage signing」，Xcode 会自动帮你修复。 - 派生数据过大：Xcode 默认不清理中间产物。我习惯每个月清一次：Cmd+Shift+K 清理构建文件夹，或者直接去 Derived Data 目录
rm -rf *。 - Deployment Target 设太高：如果你把最低版本设成 iOS 17，但同事的手机还是 iOS 16，他根本跑不起来。团队协作时，这个值应该写在项目文档里。
- 忘记切换 Scheme：Archive 的时候一定要选 Generic iOS Device，而不是某个模拟器。我见过有人对着真机设备点 Archive，结果报错说设备不匹配。
基础配置做扎实了，后面编译 SDK 时才能心不慌。下一件事情就是真正的 SDK 项目创建与结构组织了。