要点

Xcode 包含平台 SDK、编译与签名工具。模拟器运行、真机签名和商店发布是不同阶段。

第一步：安装 Xcode

1.1 检查系统要求

开发 iOS 应用前，先在 Apple 的 Xcode 系统要求中核对当前 Xcode 与 macOS 的组合；课程不以一个未锁定的小版本作为永久基线。你的工程应记录实际 Xcode、SDK、Swift language mode 与 deployment target，升级 Xcode 前再复核项目依赖和最低系统版本。

• 磁盘空间：Xcode、平台组件、模拟器与派生数据会持续增长。安装前查看磁盘余量；为首次安装与一个模拟器保留足够空间，遇到下载失败先检查空间而不是反复重装。
• Apple Account / Team：模拟器不需要签名。要在个人设备安装应用，在 Xcode 的 Apple Accounts 登录 Apple Account，并在 Signing & Capabilities 中选择 Personal Team 或已加入的开发团队。App Store、TestFlight、受限能力和分发需要相应的 Apple Developer Program 资格。

1.2 通过 App Store 安装（推荐）

1. 打开 App Store，搜索 “Xcode”
2. 点击”获取”并等待下载完成（体积大，建议有线网络）
3. 首次启动 Xcode 时会提示安装附加组件，输入管理员密码确认

1.3 安装 Command Line Tools

即使不写命令行程序，很多工具（git、swiftc、simctl）也依赖它：

# 方式一：独立安装
xcode-select --install

1. 方式二：Xcode 已装好后直接切换路径
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer

1. 验证安装
xcode-select -p
swift --version   # 记录输出；它应与当前 xcode-select 指向的开发者目录一致

💡 如果只做命令行/服务端开发，或需要在多个 Swift 版本之间切换，可以用 swiftly 独立管理 Swift 工具链（见 swift.org/install）。iOS 开发仍以 Xcode 内置工具链为主。

1.4 先验证纯 Swift 工具链

下面程序只使用 Swift 标准库。把它保存为 ToolchainCheck.swift，执行 swift ToolchainCheck.swift；它能把 Swift 编译器/运行时问题与 Xcode 工程、SwiftUI 和模拟器问题分开。

struct ToolchainCheck {
    let language: String
    let ready: Bool
}

let checks = [
    ToolchainCheck(language: "Swift", ready: true),
    ToolchainCheck(language: "standard library", ready: true),
]
precondition(checks.allSatisfy(.ready))
print("Swift toolchain check passed")

它不导入 SwiftUI 或 Apple 平台 SDK。成功只说明这一段纯 Swift 代码能够编译并运行；不能代替 Xcode 项目构建、iOS 模拟器、签名、SwiftUI 或 SwiftData 验收。

第二步：创建第一个项目

2.1 选择模板

启动 Xcode → File > New > Project（快捷键 ⇧⌘N）→ 选择 iOS > App：

💡 Interface 一定选 SwiftUI。选择 Storyboard 的模板属于旧式 UIKit 工作流，与本模块学习路径不符。

2.2 认识项目结构

SwiftNotes/
├── SwiftNotesApp.swift      # App 入口（@main）
├── ContentView.swift        # 默认根视图
├── Assets.xcassets          # 图片、颜色、App 图标资源
└── SwiftNotes.entitlements  # 能力声明文件（按需生成）
SwiftNotes.xcodeproj         # 项目配置文件（Targets、签名、构建设置）

第三步：使用模拟器

3.1 运行应用

1. Xcode 左上角先选择当前 scheme，再选一个已安装、且系统版本不低于项目 deployment target 的模拟器；不要把某个手机型号名称当作必然存在。
2. 按 ⌘R 编译并运行，并在活动区记录 Build succeeded 或首个错误。
3. 首次启动模拟器较慢，属正常现象

3.2 常用模拟器技巧

# 命令行列出所有可用设备
xcrun simctl list devices available

1. 截图模拟器屏幕
xcrun simctl io booted screenshot ~/Desktop/shot.png

1. 清除某个专门用于练习的模拟器的所有数据；先用 list 获取实际 UDID。
1. 此操作不可恢复，不能对包含要保留数据的模拟器执行。
xcrun simctl erase <UDID>

模拟器窗口内的常用快捷键：

• ⌘S：截屏（保存到桌面）
• ⌘⇧H：模拟 Home 键
• ⌘R（模拟器内）：屏幕旋转
• 菜单 Device > Erase All Content and Settings：恢复出厂状态

3.3 真机调试

模拟器能验证基础 UI、导航与很多系统行为，但不能完整复制真实设备的性能和硬件能力。摄像头、推送、传感器、后台限制、发布构建等需要真机或相应服务验收。真机调试步骤：

1. 用数据线连接 iPhone
2. iPhone 上信任该电脑
3. Xcode 中 Settings > Accounts 添加 Apple ID
4. 选择你的 iPhone 作为运行目标，⌘R 运行
5. 保持 Xcode 的 Automatically manage signing 开启；Xcode 会注册设备并创建开发 provisioning profile。若系统提示，按设备上的开发者模式或信任流程完成授权；界面路径会随 iOS 版本变化，以设备提示为准。

第四步：理解开发者账号

学习阶段使用免费账号完全够用；等到准备发布第一个项目（见 08-first-project.md）再考虑付费账号。

⚠️ 免费账号的签名 7 天过期后应用会无法启动，重新运行一次即可续签。这是”为什么我的 App 突然打不开了”的高频问题。

最佳实践

先确认项目实际使用哪个 Xcode 和命令行工具路径，再创建并运行一个最小应用；多版本并存时把所选版本记录在工程说明和 CI 中。自动更新方便个人试学，团队复现构建则需要明确升级时机。

Organization Identifier 可以由多个项目共用，完整 Bundle Identifier 才用于区分应用。模拟器足以开始界面学习，真机和开发者计划需求由具体能力与分发方式决定，不预先承诺免费配置能覆盖所有功能。

常见问题

Q1: swift --version 报错 “command not found”？

Command Line Tools 未安装或未指向 Xcode。执行 xcode-select --install，或检查 xcode-select -p 的输出路径是否正确。

Q2: 真机运行报 “Signing certificate is invalid”？

在 Xcode Settings > Accounts 中选中账号点击 “Download Manual Profiles”，或删除钥匙串中的旧证书后重新运行项目让 Xcode 自动重建签名。

Q3: 模拟器黑屏或卡死？

菜单 Device > Restart 重启模拟器；仍无效时执行 xcrun simctl shutdown all 后重新运行，或直接 Erase 设备数据。

练习与实践

练习一：基础练习

• [ ] 安装 Xcode，记录 xcodebuild -version、xcode-select -p 与 swift --version
• [ ] 创建名为 SwiftNotes 的 SwiftUI 项目，选择已安装且满足 deployment target 的模拟器，构建并运行模板页
• [ ] 修改首页文本，停止后再次运行，确认正在运行的是刚修改的 target
• [ ] 用 xcrun simctl 截取 booted 模拟器屏幕截图；若没有 booted 设备，先记录“未验证”而不是伪造成功

进阶挑战

• [ ] 连接真机并将项目运行在自己的 iPhone 上
• [ ] 在模拟器中打开深色模式（⌘⇧A），观察界面变化

相关文档

• 第一个 SwiftUI 应用
• Swift 语法要点
• View 与状态
• SwiftUI 布局
• SwiftUI Navigation