Back to Details

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 TypePrimary ToolWhen 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
ls Package.swift *.xcworkspace *.xcodeproj 2>/dev/null

List schemes and targets (auto-detects project)

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

xcodebuild -list
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.
GoalCommand
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]
GoalCommand
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
or 
-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

常用目标配置

PlatformDestination 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

参考文件

TopicFileWhen to Read
Project Discoveryproject-discovery.mdMixed projects, shared schemes
Swift Package Managerswift-package-manager.mdCross-compilation, Package.swift syntax
xcodebuild Basicsxcodebuild-basics.mdBuild settings, SDK selection
Destinationsdestinations.mdAll platforms, multiple destinations
Testingtesting.mdTest filtering, parallel execution, coverage
Archivingarchiving.mdArchive creation
Troubleshootingtroubleshooting.mdBuild/test failures, error recovery
主题文件阅读场景
项目探索project-discovery.md混合项目、共享scheme
Swift Package Managerswift-package-manager.md交叉编译、Package.swift语法
xcodebuild基础xcodebuild-basics.md构建设置、SDK选择
目标配置destinations.md全平台支持、多目标配置
测试testing.md测试过滤、并行执行、覆盖率
归档archiving.md归档文件创建
故障排除troubleshooting.md构建/测试失败、错误恢复

Common Pitfalls

常见误区

  1. swift build with Xcode submodules: Only works for standalone packages. Use 
    xcodebuild
    with the package's scheme instead.
  2. Missing destination for iOS: Use 
    -destination 'generic/platform=iOS'
    for builds, or specify a simulator for tests.
  3. Unnecessary workspace flag: Only use 
    -workspace
    for CocoaPods or multi-project setups. Standard projects with SPM dependencies just use 
    .xcodeproj
    .
  4. Case-sensitive scheme names: Run 
    xcodebuild -list
    to see exact scheme names.
  5. Outdated simulator names: Names change with Xcode versions. Run 
    xcrun simctl list devices available
    .
  6. Code signing errors: Add 
    CODE_SIGNING_ALLOWED=NO
    for builds that don't require signing.
  1. 使用swift build处理Xcode子模块：仅适用于独立包。请改用带包scheme的
    xcodebuild
    命令。
  2. iOS项目缺少目标配置：构建时使用
    -destination 'generic/platform=iOS'
    ，测试时指定模拟器。
  3. 不必要的workspace参数：仅在CocoaPods或多项目配置场景下使用
    -workspace
    。包含SPM依赖的标准项目只需使用
    .xcodeproj
    。
  4. scheme名称大小写敏感：运行
    xcodebuild -list
    查看准确的scheme名称。
  5. 模拟器名称过时：名称随Xcode版本变化。运行
    xcrun simctl list devices available
    查看最新列表。
  6. 代码签名错误：对于无需签名的构建，添加
    CODE_SIGNING_ALLOWED=NO
    参数。