安装
让 SwiftUI 模板在 iOS 模拟器中完成构建并运行。
本指南带你从全新克隆走到在 iOS 模拟器中运行应用。
应用在零密钥下即可构建并启动。每项服务都会优雅降级——缺失某个密钥时对应控制器 会空转而非崩溃——因此你可以在配置任何东西之前先把整个应用跑起来。之后再通过 配置逐步接入服务。
前置条件
- 装有 Xcode 16+ 的 macOS。 项目使用 Xcode 26.x 打造，但最低部署目标为 iOS 17.0。
- 一个 iOS 17+ 模拟器 —— iPhone 17 Pro 是测试所针对的标准模拟器 —— 或一台 iOS 17+ 真机。
- 付费 Apple 开发者团队 —— 仅在需要真机运行以验证 APNs 推送注册时才需要。模拟器 构建使用默认签名身份即可。参见推送通知。
步骤
克隆并打开
git clone <repo-url>
cd soar-swift
open SoarStarterSwift.xcodeproj让 Swift Package Manager 解析依赖
首次打开时，Xcode 会解析包依赖。请等它完成后再构建：
- Kingfisher（图片加载）
supabase-swift（认证、PostgREST、存储）purchases-ios（RevenueCat）posthog-ios（数据分析）sentry-cocoa（崩溃上报）- GoogleSignIn（原生 Google 登录）
（可选）创建密钥文件
复制示例文件，创建本地、被 git 忽略的密钥文件：
cp Secrets.example.xcconfig Secrets.xcconfig这一步是可选的——首次运行可跳过。被追踪的 AppConfig.xcconfig 提供了安全占位值，
任何仍为占位值的键都会被视为未设置。密钥参考见配置。
构建并运行
选择 SoarStarterSwift scheme 与某个 iPhone 模拟器，然后按 ⌘R。应用会启动到 同意 → 引导 → 登录的流程。
命令行构建与运行
标准命令（与模板的 CLAUDE.md 一致）：
# 构建（Debug，iPhone 17 Pro 模拟器 —— 测试所用的标准目标）
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
xcodebuild -project SoarStarterSwift.xcodeproj \
-scheme SoarStarterSwift \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
build
# 运行单元测试 + UI 测试
xcodebuild -project SoarStarterSwift.xcodeproj \
-scheme SoarStarterSwift \
-destination 'platform=iOS Simulator,name=iPhone 17 Pro' \
-parallel-testing-enabled NO \
test测试必须加 -parallel-testing-enabled NO。 默认情况下 xcodebuild 会把目标克隆到
多个模拟器，并让单元测试目标与 XCUITest 冒烟测试目标并行运行；单元测试套件会占满 CPU，
导致冒烟测试首个 waitForExistence（引导页）超时。串行执行可避免二者互相抢占资源。
只有在装了多个 Xcode 版本且 xcode-select 指向别处时，才需要 DEVELOPER_DIR。
Debug 构建后，在已启动的模拟器上安装并运行：
# 若没有运行中的模拟器，先启动一个
xcrun simctl boot "iPhone 17 Pro" && open -a Simulator
# 安装构建出的 .app，再按 bundle id 启动
xcrun simctl install booted /path/to/Build/Products/Debug-iphonesimulator/SoarStarterSwift.app
xcrun simctl launch booted com.soarstarter.SoarStarterSwiftBundle id 为 com.soarstarter.SoarStarterSwift。
验证安装
在未配置任何密钥的情况下，确认应用能走通启动闸门：
- 首先出现 同意 页面，并可以接受。
- 引导页 —— 四页轮播能翻页并完成。
- 登录 页面正常渲染（邮箱/密码输入框 + 社交登录按钮；
GOOGLE_IOS_CLIENT_ID未设置前 Google 按钮为暗色）。 - 组件画廊 —— Component 标签页可离线工作（它以各种状态渲染本地 UI，无需联网）。
认证、待办、订阅和上传都需要 Supabase 项目——继续阅读 Supabase 配置。
常见首次运行问题
| 现象 | 可能原因 | 解决办法 |
|---|---|---|
在 import Kingfisher / import Supabase 处构建失败 | SPM 尚未解析完成 | 等待包解析完成，或执行 File → Packages → Resolve Package Versions |
xcodebuild 使用了错误的工具链 | 安装了多个 Xcode 版本 | 加前缀 DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer |
Unable to find a destination | 指定的模拟器不存在 | 在 Xcode 中创建 iPhone 17 Pro 模拟器，或修改 -destination 名称 |
| UI 测试启动时抖动/超时 | 启用了并行测试 | 始终传入 -parallel-testing-enabled NO |
| 真机 运行时签名报错 | 未选择付费团队 | 在 Signing & Capabilities 中设置团队（真机推送需付费团队） |