swift-development

Swift 开发

前置条件

• 安装了 Xcode 15+ 的 macOS（Swift 6 需要 Xcode 16+）
• Xcode 命令行工具：xcode-select --install
• 验证：xcodebuild -version 和 swift --version

快速开始

新建 Swift Package

# Use the included script for full setup
./scripts/new_package.sh MyLibrary --type library --ios --macos

# Or manually
swift package init --type library --name MyLibrary

构建和测试

# SPM packages
swift build
swift test

# Xcode projects
xcodebuild -workspace App.xcworkspace -scheme App \
    -destination 'platform=iOS Simulator,name=iPhone 15' build

# Use included script for common options
./scripts/run_tests.sh --parallel --coverage

格式化和代码检查

# Use included script
./scripts/format_and_lint.sh Sources/

# Check mode (CI)
./scripts/format_and_lint.sh --check

模拟器管理

# Use included script
./scripts/simulator.sh list
./scripts/simulator.sh boot "iPhone 15"
./scripts/simulator.sh screenshot
./scripts/simulator.sh dark

---

核心工作流

构建 iOS 应用

# Debug build for simulator
xcodebuild -workspace App.xcworkspace -scheme App \
    -destination 'platform=iOS Simulator,name=iPhone 15' \
    build

# Release archive
xcodebuild archive \
    -workspace App.xcworkspace -scheme App \
    -archivePath ./build/App.xcarchive \
    -configuration Release

# Export IPA (use templates from assets/ExportOptions/)
xcodebuild -exportArchive \
    -archivePath ./build/App.xcarchive \
    -exportPath ./build/export \
    -exportOptionsPlist assets/ExportOptions/app-store.plist

测试

# All tests
xcodebuild test -workspace App.xcworkspace -scheme App \
    -destination 'platform=iOS Simulator,name=iPhone 15'

# Specific test
xcodebuild test -only-testing:AppTests/MyTestClass/testMethod

# With coverage
xcodebuild test -enableCodeCoverage YES \
    -resultBundlePath ./TestResults.xcresult

安装应用

# Install on booted simulator
xcrun simctl install booted ./Build/Products/Debug-iphonesimulator/App.app

# Launch
xcrun simctl launch booted com.company.app

---

官方文档

参考链接（供人工查阅）

以下是 Apple 官方文档链接，供手动浏览：

资源	URL
Swift 文档	https://developer.apple.com/documentation/swift
SwiftUI	https://developer.apple.com/documentation/swiftui
Swift 并发	https://developer.apple.com/documentation/swift/concurrency
Swift Testing	https://developer.apple.com/documentation/testing

注意：Apple 的文档网站是 JavaScript SPA，无法通过 WebFetch 以编程方式获取。请改用下方基于 GitHub 的来源。

兼容 WebFetch 的来源（GitHub 原始 URL）

始终使用 raw.githubusercontent.com URL——常规的 github.com URL 会返回乱码 HTML/JSON。

基础 URL 前缀：https://raw.githubusercontent.com/apple

Swift Testing（/swift-testing/main/）：

资源	路径
README	README.md
定义测试	Sources/Testing/Testing.docc/DefiningTests.md
组织测试	Sources/Testing/Testing.docc/OrganizingTests.md
预期	Sources/Testing/Testing.docc/Expectations.md
参数化测试	Sources/Testing/Testing.docc/ParameterizedTesting.md
特征概览	Sources/Testing/Testing.docc/Traits.md
特征参考	Sources/Testing/Testing.docc/Traits/Trait.md
添加标签	Sources/Testing/Testing.docc/AddingTags.md
添加注释	Sources/Testing/Testing.docc/AddingComments.md
关联缺陷	Sources/Testing/Testing.docc/AssociatingBugs.md
缺陷标识符	Sources/Testing/Testing.docc/BugIdentifiers.md
附件	Sources/Testing/Testing.docc/Attachments.md
启用/禁用测试	Sources/Testing/Testing.docc/EnablingAndDisabling.md
限制执行时间	Sources/Testing/Testing.docc/LimitingExecutionTime.md
并行化	Sources/Testing/Testing.docc/Parallelization.md
退出测试	Sources/Testing/Testing.docc/exit-testing.md
已知问题	Sources/Testing/Testing.docc/known-issues.md
测试异步代码	Sources/Testing/Testing.docc/testing-asynchronous-code.md
测试错误	Sources/Testing/Testing.docc/testing-for-errors-in-swift-code.md
从 XCTest 迁移	Sources/Testing/Testing.docc/MigratingFromXCTest.md
愿景与设计	Documentation/Vision.md
CLI 调试	Documentation/CommandlineDebugging.md
环境变量	Documentation/EnvironmentVariables.md

其他 Swift Package：

资源	完整原始 URL
Swift Async Algorithms	https://raw.githubusercontent.com/apple/swift-async-algorithms/main/README.md
Swift Collections	https://raw.githubusercontent.com/apple/swift-collections/main/README.md

对于 Swift Evolution 提案，请根据提案编号构造原始 URL： https://raw.githubusercontent.com/apple/swift-evolution/main/proposals/NNNN-proposal-name.md

示例：https://raw.githubusercontent.com/apple/swift-evolution/main/proposals/0409-access-level-on-imports.md

发现目录内容时（查找提案编号、文档文件名）：请使用 WebSearch 而非 WebFetch——GitHub 上的目录列表无法解析。

何时获取文档

在以下情况下，使用 WebFetch 搭配 GitHub 原始 URL：

1. Swift Testing：需要了解 @Test、#expect、#require、特征或参数化测试的详细信息时
2. Swift Evolution：查看新语言特性的已接受提案时
3. 框架详情：实现 Apple 开源 Swift 软件包中的功能时
4. 不确定时：不确定当前的 API 模式或最佳实践时

URL 转换规则：将 github.com/{owner}/{repo}/blob/{branch}/ 替换为 raw.githubusercontent.com/{owner}/{repo}/{branch}/

备用方案：如果 WebFetch 无法访问原始 URL，使用 WebSearch 搜索 site:github.com/apple {topic}，查找正确的文件路径，然后构造原始 URL。

WebFetch 提示词示例：“从本文档中提取主要功能、宏和用法示例”

---

参考文件

特定主题的详细文档：

主题	文件
SwiftUI 模式	references/swiftui-patterns.md
测试模式	references/testing-patterns.md
Swift 6 并发	references/concurrency.md
架构模式	references/architecture.md
最佳实践	references/best-practices.md
Swift Package Manager	references/spm.md
xcodebuild 命令	references/xcodebuild.md
模拟器控制	references/simctl.md
代码签名	references/code-signing.md
CI/CD 设置	references/cicd.md
故障排除	references/troubleshooting.md

---

附带脚本

脚本	用途
scripts/new_package.sh	使用配置文件创建新的 Swift 软件包
scripts/run_tests.sh	使用常用选项运行测试
scripts/format_and_lint.sh	格式化并检查 Swift 代码
scripts/simulator.sh	快速管理模拟器

---

资源模板

资源	用途
assets/Package.swift.template	Swift 软件包模板
assets/.swiftformat	SwiftFormat 配置
assets/.swiftlint.yml	SwiftLint 配置
assets/ExportOptions/	归档导出 plist 模板

---

快速参考

基本命令

任务	命令
构建软件包	swift build
构建发布版本	swift build -c release
运行测试	swift test
更新依赖项	swift package update
列出模拟器	xcrun simctl list devices
启动模拟器	xcrun simctl boot "iPhone 15"
安装应用	xcrun simctl install booted ./App.app
格式化代码	swiftformat .
检查代码	swiftlint

常用目标设备

# iOS Simulator
-destination 'platform=iOS Simulator,name=iPhone 15'

# macOS
-destination 'platform=macOS'

# Generic iOS (for archives)
-destination 'generic/platform=iOS'

---