# 构建 Apple 平台产品为 Apple 平台构建、测试、存档、部署和自动化 Swift 包和 Xcode 项目。 ## 何时使用此技能当您需要执行以下操作时，请使用此技能： * 构建 iOS、macOS、tvOS、watchOS 或 VisionOS 应用程序 * 构建一个 Swift 包 * 运行单元测试或UI测试 * 创建一个存档用于分发 * 发现项目结构（方案、目标、配置） * 管理模拟器（创建、启动、配置、安装应用程序） * 部署到物理设备 * 自动化模拟器测试（权限、推送通知、屏幕截图、位置） * 签署、公证或分发应用程序 * 检查二进制文件或调试符号 * 配置应用程序性能 * 解析xcrun工具路径或切换Xcode版本 ## xcrun 工具解析 `xcrun` 解析并执行 Xcode 开发人员工具，无需硬编码路径。本技能中的所有工具均通过 xcrun 访问（例如，“xcrun simctl”、“xcrun devicectl”、“xcrun xctrace”）。目标|命令 ---|--- 查找刀具路径 | `xcrun --find <工具>` 显示SDK路径| `xcrun --sdk iphoneos --show-sdk-path` 切换 Xcode（每个命令）| `DEVELOPER_DIR=/path/to/Xcode.app/Contents/Developer xcrun <工具>` 切换 Xcode（系统）| `sudo xcode-select -s /Applications/Xcode.app/Contents/Developer` 升级后清除缓存 | `xcrun --kill-cache` 有关工具解析优先级、工具链选择或调试的信息，请参阅 [xcrun-basics.md]()。 ## 工具选择项目类型 |主要工具|何时使用 ---|---|--- 独立的 `Package.swift` | `快速构建` |库、CLI 工具、跨平台 Swift（无 .xcodeproj） `.xcworkspace` | `xcodebuild-工作空间` | CocoaPods 或多项目设置 `.xcodeproj` | `xcodebuild` |标准 Xcode 项目（包括具有 SPM 依赖项的项目） **重要**：`swift build` / `swift test` 命令仅适用于 **独立 Swift 包**。如果 Swift 包作为子模块嵌入到 Xcode 项目中，则必须使用带有适当方案的“xcodebuild”——Swift CLI 无法在该上下文中编排构建。 ## 项目发现在构建之前，先了解一下项目结构： # 查找存在哪些项目文件 ls Package.swift *.xcworkspace *.xcodeproj 2>/dev/null # 列出方案和目标（自动检测项目） xcodebuild-列表 # 描述包（仅限独立 SPM）快速包描述 **注意**：当 Xcode 项目引用本地 Swift 包时，每个包 **target** 都会获得自己的方案（以目标而不是包命名）。使用这些方案来构建单独的目标，而无需构建整个应用程序。对于混合项目、共享方案或详细的输出解析，请参阅 [project-discovery.md]()。 ## Swift 包管理器命令 **重要**：这些命令仅适用于独立的 Swift 包，不适用于 Xcode 项目中的 Swift Package Manager 子模块。目标|命令 ---|--- 构建（调试）| `快速构建` 构建（发布）| `快速构建-c发布` 运行可执行文件 | `快速运行[<目标>]` 运行测试 | `快速测试` 运行特定测试 | `swift test --filter ` 显示二进制路径 | `快速构建 --show-bin-path` 清洁| `快速打包干净` 初始化 | `swift package init [--类型库|可执行文件]` 有关交叉编译、Package.swift 语法或依赖项管理，请参阅 [swift-package-manager.md]()。 ## xcodebuild 命令 **命令结构** : `xcodebuild [action] -scheme [-workspace|-project] [options] [BUILD_SETTING=value]` 目标|命令 ---|--- 列表方案| `xcodebuild-列表` 构建 | `xcodebuild 构建-方案 <名称>` 测试| `xcodebuild test -scheme -destination ''` 为测试而构建 | `xcodebuild build-for-testing -scheme -destination ''` 无需构建即可测试 | `xcodebuild test-without-building -scheme -destination ''` 档案 | `xcodebuild archive -scheme <名称> -archivePath <路径>.xcarchive` 清洁| `xcodebuild clean -scheme <名称>` **必需**：“-scheme”始终是必需的。如果存在多个，请添加“-workspace”或“-project”。 **对于测试**：iOS/tvOS/watchOS/visionOS 目标需要 `-destination`。有关构建设置、SDK 选择或 CI 配置，请参阅 [xcodebuild-basics.md]()。 ## 常见目的地平台|目的地说明符 ---|--- macOS | `'平台=macOS'` iOS 模拟器 | `'平台=iOS模拟器，名称=iPhone 17'` iOS 设备 | `'平台=iOS，id='` tvOS 模拟器 | `'平台=tvOS模拟器，名称=Apple TV'` watchOS 模拟器 | `'平台=watchOS模拟器，名称=Apple Watch Series 11 (46mm)'` VisionOS模拟器| `'平台=visionOS模拟器，名称=Apple Vision Pro'` 通用（仅限构建）| `'通用/平台=iOS'` **注意**：模拟器名称随每个 Xcode 版本而变化。始终验证可用的模拟器： xcrun simctl 列出可用的设备对于所有平台、多个目标或对目标错误进行故障排除，请参阅 [destinations.md]()。 ## 模拟器管理（simctl） `xcrun simctl` 管理完整的模拟器生命周期并启用测试自动化，而无需启动 Xcode。目标|命令 ---|--- 列出可用的模拟器 | `xcrun simctl 列出可用的设备` 创建模拟器| `xcrun simctl create "<名称>" "<类型>" "<运行时>"` 开机/关机| `xcrun simctl boot ` / `xcrun simctl shutdown ` 安装应用程序 | `xcrun simctl install booted ` 启动应用程序 | `xcrun simctl launch booted ` 授予权限| `xcrun simctl 隐私启动授予所有 ` 推送通知 | `xcrun simctl Push 启动 ` 设置外观| `xcrun simctl ui 启动外观黑暗` 覆盖状态栏| `xcrun simctl status_bar 启动覆盖 --time "9:41"` 打开 URL / 深层链接 | `xcrun simctl openurl 启动“”` 截图| `xcrun simctl io 启动屏幕截图 ` 录制视频 | `xcrun simctl io 启动 recordVideo ` 设置位置 | `xcrun simctl 启动位置设置 ,` 流日志 | `xcrun simctl spawn 启动日志流 --predicate '...'` 下载运行时 | `xcodebuild -下载平台 iOS` 有关应用程序生命周期、环境变量、隐私服务、媒体、诊断和运行时管理的信息，请参阅 [simctl.md]()。 ## 物理设备部署 (devicectl) `xcrun devicectl` 管理运行 iOS 17+ 的物理设备。在 Xcode 15 中引入。目标|命令 ---|--- 列出设备 | `xcrun devicectl 列出设备` 列出设备 (JSON) | `xcrun devicectl list devices --json-output /tmp/devices.json` 安装应用程序 | `xcrun devicectl 设备安装应用程序 --device <路径>` 启动应用程序 | `xcrun devicectl 设备进程启动 --device

` 从设备复制文件 | `xcrun devicectl 设备复制 --device ...` 列出已安装的应用程序 | `xcrun devicectl 设备信息应用程序 --device ` **重要**：需要 iOS 17+、启用开发者模式以及有效的代码签名。 JSON 输出是唯一稳定的脚本接口。有关文件传输、进程管理、设备配对、限制和故障排除的信息，请参阅 [devicectl.md]()。 ## 代码签名目标|命令 ---|--- 列出签名身份 | `安全查找身份-v -p 协同设计` 禁用签名（构建）| `代码_签名_允许=否` 自动配置| `-allowProvisioningUpdates` 验证签名 | `codesign --verify --verbose=4 MyApp.app` 有关 CI 钥匙串设置、手动与自动签名以及构建设置，请参阅 [code-signing.md]()。 ## 参考文件主题 |文件|何时阅读 ---|---|--- xcrun 基础知识 | [xcrun-basics.md]() |工具解析、Xcode切换、SDK路径项目发现| [project-discovery.md]() |混合项目，共享方案 Swift 包管理器 | [swift-package-manager.md]() |交叉编译，Package.swift语法 xcodebuild 基础知识 | [xcodebuild-basics.md]() |构建设置、SDK 选择目的地 | [destinations.md]() |全平台、多目的地测试| [testing.md]() |测试过滤、并行执行、覆盖率归档| [archiving.md]() |档案创建模拟器管理 | [simctl.md]() |设备生命周期、应用程序管理、自动化物理设备| [devicectl.md]() | iOS 17+ 设备部署代码签名 | [code-signing.md]() |证书、配置、CI 钥匙串分析与结果 | [profiling-and-results.md]() | xctrace、xcresulttool、覆盖率分销| [distribution.md]() | IPA导出、公证、App Store上传二进制工具 | [binary-tools.md]() | lipo、otool、dsymutil、atos、plutil、docc CI/CD 模式 | [ci-cd-patterns.md]() |完整的管道、GitHub Actions、日志捕获故障排除 | [troubleshooting.md]() |所有主题的错误索引 ## 常见陷阱 1. **使用 Xcode 子模块进行快速构建**：仅适用于独立包。请使用 `xcodebuild` 和包的方案。 2. **缺少 iOS 目标**：使用 `-destination 'generic/platform=iOS'` 进行构建，或指定模拟器进行测试。 3. **不必要的工作区标志** ：仅对 CocoaPods 或多项目设置使用 `-workspace`。具有 SPM 依赖项的标准项目只需使用“.xcodeproj”。 4. **区分大小写的方案名称**：运行 `xcodebuild -list` 以查看确切的方案名称。 5. **过时的模拟器名称**：名称随 Xcode 版本而变化。运行“xcrun simctl list devices available”。 6. **代码签名错误** ：为不需要签名的构建添加“CODE_SIGNING_ALLOWED=NO”。 7. **陈旧的 xcrun 缓存** ：Xcode 升级后，运行 `xcrun --kill-cache`。 8. **devicectl 仅适用于 iOS 17+** ：旧设备对 devicectl 不可见。 9. **xctrace 输出到 stderr** ：解析“xcrun xctrace list devices”时使用“2>&1”重定向。 10. **用于脚本编写的 JSON 输出** ：“simctl”和“devicectl”都提供 JSON 输出标志 - 始终更喜欢结构化输出而不是解析人类可读的文本。

构建 Apple 平台产品

包含技能