building-apple-platform-products

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building Apple Platform Products

构建Apple平台产品

Build, test, and archive Swift packages and Xcode projects for Apple platforms.

为Apple平台构建、测试并归档Swift包与Xcode项目。

When to Use This Skill

何时使用该技能

Use this skill when you need to:

Build an iOS, macOS, tvOS, watchOS, or visionOS app
Build a Swift package
Run unit tests or UI tests
Create an archive for distribution
Discover project structure (schemes, targets, configurations)

当你需要以下操作时使用该技能：

构建iOS、macOS、tvOS、watchOS或visionOS应用
构建Swift包
运行单元测试或UI测试
创建用于分发的归档文件
探索项目结构（schemes、targets、配置）

Tool Selection

工具选择

Project Type	Primary Tool	When to Use
Standalone `Package.swift`	`swift build`	Libraries, CLI tools, cross-platform Swift (no .xcodeproj)
`.xcworkspace`	`xcodebuild -workspace`	CocoaPods or multi-project setups
`.xcodeproj`	`xcodebuild`	Standard Xcode projects (including those with SPM dependencies)

Important: The

swift build

swift test

commands only work for standalone Swift packages. If a Swift package is embedded as a submodule within an Xcode project, you must use

xcodebuild

with the appropriate scheme—the Swift CLI cannot orchestrate builds in that context.

项目类型	主要工具	使用场景
独立 `Package.swift`	`swift build`	库、CLI工具、跨平台Swift项目（无.xcodeproj）
`.xcworkspace`	`xcodebuild -workspace`	CocoaPods或多项目配置
`.xcodeproj`	`xcodebuild`	标准Xcode项目（包含SPM依赖的项目）

重要提示：

swift build

swift test

命令仅适用于独立Swift包。如果Swift包作为子模块嵌入到Xcode项目中，必须使用

xcodebuild

并指定对应的scheme——Swift CLI无法在此场景下协调构建。

Project Discovery

项目探索

Before building, discover the project structure:

bash

undefined

在构建前，先探索项目结构：

bash

undefined

Find what project files exist

查找存在的项目文件

ls Package.swift *.xcworkspace *.xcodeproj 2>/dev/null

List schemes and targets (auto-detects project)

列出schemes与targets（自动检测项目）

xcodebuild -list

Describe package (standalone SPM only)

描述包信息（仅适用于独立SPM项目）

swift package describe


**Note**: When an Xcode project references a local Swift package, each package **target** gets its own scheme (named after the target, not the package). Use these schemes to build individual targets without building the entire app.

For mixed projects, shared schemes, or detailed output parsing, see [project-discovery.md](references/project-discovery.md).

swift package describe


**注意**：当Xcode项目引用本地Swift包时，每个包**target**会拥有自己的scheme（以target命名，而非包名）。可使用这些scheme来构建单个target，无需构建整个应用。

对于混合项目、共享scheme或需要解析详细输出的场景，请查看[project-discovery.md](references/project-discovery.md)。

Swift Package Manager Commands

Swift Package Manager命令

Important: These commands only work for standalone Swift packages, not Swift Package Manager submodules in Xcode projects.

Goal	Command
Build (debug)	`swift build`
Build (release)	`swift build -c release`
Run executable	`swift run [<target>]`
Run tests	`swift test`
Run specific test	`swift test --filter <TestClass.testMethod>`
Show binary path	`swift build --show-bin-path`
Clean	`swift package clean`
Initialize	`swift package init [--type library\|executable]`

For cross-compilation, Package.swift syntax, or dependency management, see swift-package-manager.md.

重要提示：这些命令仅适用于独立Swift包，不适用于Xcode项目中的Swift Package Manager子模块。

目标	命令
构建（debug模式）	`swift build`
构建（release模式）	`swift build -c release`
运行可执行文件	`swift run [<target>]`
运行测试	`swift test`
运行指定测试	`swift test --filter <TestClass.testMethod>`
显示二进制文件路径	`swift build --show-bin-path`
清理	`swift package clean`
初始化	`swift package init [--type library\|executable]`

如需了解交叉编译、Package.swift语法或依赖管理，请查看swift-package-manager.md。

xcodebuild Commands

xcodebuild命令

Command structure:

xcodebuild [action] -scheme <name> [-workspace|-project] [options] [BUILD_SETTING=value]

Goal	Command
List schemes	`xcodebuild -list`
Build	`xcodebuild build -scheme <name>`
Test	`xcodebuild test -scheme <name> -destination '<spec>'`
Build for testing	`xcodebuild build-for-testing -scheme <name> -destination '<spec>'`
Test without build	`xcodebuild test-without-building -scheme <name> -destination '<spec>'`
Archive	`xcodebuild archive -scheme <name> -archivePath <path>.xcarchive`
Clean	`xcodebuild clean -scheme <name>`

Required:

-scheme

is always required. Add

-workspace

-project

when multiple exist. For tests:

-destination

is required for iOS/tvOS/watchOS/visionOS targets.

For build settings, SDK selection, or CI configuration, see xcodebuild-basics.md.

命令结构：

xcodebuild [action] -scheme <name> [-workspace|-project] [options] [BUILD_SETTING=value]

目标	命令
列出schemes	`xcodebuild -list`
构建	`xcodebuild build -scheme <name>`
测试	`xcodebuild test -scheme <name> -destination '<spec>'`
为测试构建	`xcodebuild build-for-testing -scheme <name> -destination '<spec>'`
不构建直接测试	`xcodebuild test-without-building -scheme <name> -destination '<spec>'`
归档	`xcodebuild archive -scheme <name> -archivePath <path>.xcarchive`
清理	`xcodebuild clean -scheme <name>`

必填项：

-scheme

始终为必填项。当存在多个项目文件时，需添加

-workspace

或

-project

。 测试相关：针对iOS/tvOS/watchOS/visionOS target，

-destination

为必填项。

如需了解构建设置、SDK选择或CI配置，请查看xcodebuild-basics.md。

Common Destinations

常用目标配置

Platform	Destination Specifier
macOS	`'platform=macOS'`
iOS Simulator	`'platform=iOS Simulator,name=iPhone 17'`
iOS Device	`'platform=iOS,id=<UDID>'`
tvOS Simulator	`'platform=tvOS Simulator,name=Apple TV'`
watchOS Simulator	`'platform=watchOS Simulator,name=Apple Watch Series 11 (46mm)'`
visionOS Simulator	`'platform=visionOS Simulator,name=Apple Vision Pro'`
Generic (build only)	`'generic/platform=iOS'`

Note: Simulator names change with each Xcode release. Always verify available simulators:

bash

xcrun simctl list devices available

For all platforms, multiple destinations, or troubleshooting destination errors, see destinations.md.

平台	目标指定参数
macOS	`'platform=macOS'`
iOS模拟器	`'platform=iOS Simulator,name=iPhone 17'`
iOS设备	`'platform=iOS,id=<UDID>'`
tvOS模拟器	`'platform=tvOS Simulator,name=Apple TV'`
watchOS模拟器	`'platform=watchOS Simulator,name=Apple Watch Series 11 (46mm)'`
visionOS模拟器	`'platform=visionOS Simulator,name=Apple Vision Pro'`
通用（仅构建）	`'generic/platform=iOS'`

注意：模拟器名称会随Xcode版本更新而变化。请始终通过以下命令验证可用模拟器：

bash

xcrun simctl list devices available

如需了解全平台支持、多目标配置或目标参数排障，请查看destinations.md。

Reference Files

参考文件

Topic	File	When to Read
Project Discovery	project-discovery.md	Mixed projects, shared schemes
Swift Package Manager	swift-package-manager.md	Cross-compilation, Package.swift syntax
xcodebuild Basics	xcodebuild-basics.md	Build settings, SDK selection
Destinations	destinations.md	All platforms, multiple destinations
Testing	testing.md	Test filtering, parallel execution, coverage
Archiving	archiving.md	Archive creation
Troubleshooting	troubleshooting.md	Build/test failures, error recovery

主题	文件	阅读场景
项目探索	project-discovery.md	混合项目、共享scheme
Swift Package Manager	swift-package-manager.md	交叉编译、Package.swift语法
xcodebuild基础	xcodebuild-basics.md	构建设置、SDK选择
目标配置	destinations.md	全平台支持、多目标配置
测试	testing.md	测试过滤、并行执行、覆盖率
归档	archiving.md	归档文件创建
故障排除	troubleshooting.md	构建/测试失败、错误恢复

Common Pitfalls

常见误区

swift build with Xcode submodules: Only works for standalone packages. Use
```
xcodebuild
```
with the package's scheme instead.
Missing destination for iOS: Use
```
-destination 'generic/platform=iOS'
```
for builds, or specify a simulator for tests.
Unnecessary workspace flag: Only use
```
-workspace
```
for CocoaPods or multi-project setups. Standard projects with SPM dependencies just use
```
.xcodeproj
```
.
Case-sensitive scheme names: Run
```
xcodebuild -list
```
to see exact scheme names.
Outdated simulator names: Names change with Xcode versions. Run
```
xcrun simctl list devices available
```
.
Code signing errors: Add
```
CODE_SIGNING_ALLOWED=NO
```
for builds that don't require signing.

使用swift build处理Xcode子模块：仅适用于独立包。请改用带包scheme的
```
xcodebuild
```
命令。
iOS项目缺少目标配置：构建时使用
```
-destination 'generic/platform=iOS'
```
，测试时指定模拟器。
不必要的workspace参数：仅在CocoaPods或多项目配置场景下使用
```
-workspace
```
。包含SPM依赖的标准项目只需使用
```
.xcodeproj
```
。
scheme名称大小写敏感：运行
```
xcodebuild -list
```
查看准确的scheme名称。
模拟器名称过时：名称随Xcode版本变化。运行
```
xcrun simctl list devices available
```
查看最新列表。
代码签名错误：对于无需签名的构建，添加
```
CODE_SIGNING_ALLOWED=NO
```
参数。