axiom-xcode-debugging

Xcode 调试

概述

调试代码前先检查构建环境。核心原则：80% 的“神秘”Xcode 问题都出在环境上（过期的 Derived Data、卡住的模拟器、僵尸进程），而不是代码错误。

示例提示

以下是开发者提出的真实问题，本技能旨在解答这些问题：

1. “我的构建失败了，显示 ‘BUILD FAILED’，但没有错误详情。我什么都没改。怎么回事？”

→ 本技能展示以环境为先的诊断方法：在检查代码前，先检查 Derived Data、模拟器状态和僵尸进程

2. “昨天测试还通过了，代码没改，今天却失败了。这真让人沮丧。怎么解决？”

→ 本技能讲解过期 Derived Data 和间歇性失败，并展示只需 2-5 分钟的修复方法（清理 Derived Data）

3. “我的应用构建正常，但运行的还是我修改前的旧代码。我重启了 Xcode，但问题依旧。”

→ 本技能说明 Derived Data 会缓存旧构建，并展示如何删除它以强制进行干净重建

4. “模拟器提示 ‘Unable to boot simulator’，我无法运行测试。如何恢复？”

→ 本技能涵盖使用 simctl 诊断模拟器状态，以及安全的恢复方法（抹掉/关机/重启）

5. “更新 SPM 依赖后出现 ‘No such module: SomePackage’ 错误。怎么解决？”

→ 本技能讲解 SPM 缓存问题，以及可解决“幽灵”模块错误的清理 Derived Data 工作流

---

危险信号 — 先检查环境

如果出现以下任意情况，请优先怀疑环境，而非代码：

• “在我的机器上能运行，但在 CI 上不行”
• “昨天测试还通过了，今天没改代码却失败了”
• “构建成功，但执行的是旧代码”
• “构建有时成功，有时失败”（间歇性失败）
• “模拟器卡在启动画面”或“无法安装应用”
• 存在多个运行时间超过 30 分钟的 xcodebuild 进程（10 个以上）

必须先做的步骤

务必先运行以下命令（再阅读代码）：

# 1. Check processes (zombie xcodebuild?)
ps aux | grep -E "xcodebuild|Simulator" | grep -v grep

# 2. Check Derived Data size (>10GB = stale)
du -sh ~/Library/Developer/Xcode/DerivedData

# 3. Check simulator states (stuck Booting?)
xcrun simctl list devices | grep -E "Booted|Booting|Shutting Down"

这些结果说明什么

• 0 个进程 + Derived Data 占用较小 + 没有已启动的模拟器 → 环境干净，检查代码
• 10 个以上进程，或 Derived Data 超过 10GB，或模拟器卡住 → 环境有问题，先清理
• 执行的是旧代码，或出现间歇性失败 → 无论大小，都要清理 Derived Data

为什么要先检查环境

• 清理环境：2-5 分钟 → 解决问题
• 调试环境问题导致的代码：30-120 分钟 → 浪费时间

快速修复工作流

查找方案名称

如果不知道方案名称：

# List available schemes
xcodebuild -list

针对过期构建 / “No such module” 错误

# Clean everything
xcodebuild clean -scheme YourScheme
rm -rf ~/Library/Developer/Xcode/DerivedData/*
rm -rf .build/ build/

# Rebuild
xcodebuild build -scheme YourScheme \
  -destination 'platform=iOS Simulator,name=iPhone 16'

针对模拟器问题

# Shutdown all simulators
xcrun simctl shutdown all

# If simctl command fails, shutdown and retry
xcrun simctl shutdown all
xcrun simctl list devices

# If still stuck, erase specific simulator
xcrun simctl erase <device-uuid>

# Nuclear option: force-quit Simulator.app
killall -9 Simulator

针对僵尸进程

# Kill all xcodebuild (use cautiously)
killall -9 xcodebuild

# Check they're gone
ps aux | grep xcodebuild | grep -v grep

针对测试失败

# Isolate failing test
xcodebuild test -scheme YourScheme \
  -destination 'platform=iOS Simulator,name=iPhone 16' \
  -only-testing:YourTests/SpecificTestClass

模拟器验证（可选）

应用修复后，可在模拟器中进行验证并确认视觉效果。

快速截图验证

# 1. Boot simulator (if not already)
xcrun simctl boot "iPhone 16 Pro"

# 2. Build and install app
xcodebuild build -scheme YourScheme \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro'

# 3. Launch app
xcrun simctl launch booted com.your.bundleid

# 4. Wait for UI to stabilize
sleep 2

# 5. Capture screenshot
xcrun simctl io booted screenshot /tmp/verify-build-$(date +%s).png

使用 Axiom 工具

快速截图：

/axiom:screenshot

完整的模拟器测试（包括导航和状态设置）：

/axiom:test-simulator

何时使用模拟器验证

适用于：

• 视觉修复 — 布局变更、UI 更新、样式微调
• 依赖状态的错误 — “只会在这个特定屏幕上发生”
• 间歇性失败 — 需要复现特定条件
• 发布前 — 最终确认修复确实有效

专业提示：如果你有调试深层链接（参见 axiom-deep-link-debugging 技能），可以直接跳转到出现问题的屏幕：

xcrun simctl openurl booted "debug://problem-screen"
sleep 1
xcrun simctl io booted screenshot /tmp/fix-verification.png

决策树

Test/build failing?
├─ BUILD FAILED with no details?
│  └─ Clean Derived Data → rebuild
├─ Build intermittent (sometimes succeeds/fails)?
│  └─ Clean Derived Data → rebuild
├─ Build succeeds but old code executes?
│  └─ Delete Derived Data → rebuild (2-5 min fix)
├─ "Unable to boot simulator"?
│  └─ xcrun simctl shutdown all → erase simulator
├─ "No such module PackageName"?
│  └─ Clean + delete Derived Data → rebuild
├─ Tests hang indefinitely?
│  └─ Check simctl list → reboot simulator
├─ Tests crash?
│  └─ Check ~/Library/Logs/DiagnosticReports/*.crash
└─ Code logic bug?
   └─ Use systematic-debugging skill instead

常见错误模式

错误	修复方法
BUILD FAILED（无详情）	删除 Derived Data
Unable to boot simulator	xcrun simctl erase <uuid>
No such module	清理并删除 Derived Data
测试挂起	检查 simctl list，重启模拟器
执行的是旧代码	删除 Derived Data

实用 CLI 工具

# Show build settings
xcodebuild -showBuildSettings -scheme YourScheme

# List schemes/targets
xcodebuild -list

# Verbose output
xcodebuild -verbose build -scheme YourScheme

# Build without testing (faster)
xcodebuild build-for-testing -scheme YourScheme
xcodebuild test-without-building -scheme YourScheme

# Version and build number management (agvtool)
xcrun agvtool what-marketing-version          # Current version (e.g., 2.0)
xcrun agvtool what-version                    # Current build number
xcrun agvtool next-version -all               # Bump build number
xcrun agvtool new-version -all 42             # Set specific build number
xcrun agvtool new-marketing-version 2.1       # Set marketing version

# Validate asset catalogs
xcrun amlint Assets.xcassets                   # Lint for issues before build

物理设备管理（devicectl）

devicectl 是用于物理设备操作的现代 CLI（取代旧版 idevice* 工具）。

# List connected devices
xcrun devicectl list devices

# Install app on device
xcrun devicectl device install app --device <udid> MyApp.app

# Launch app on device
xcrun devicectl device process launch --device <udid> com.your.bundleid

# List installed apps
xcrun devicectl device info apps --device <udid>

# List running processes
xcrun devicectl device info processes --device <udid>

使用时机：当问题无法在 Simulator 中复现时，用于物理设备调试——通过 CLI 安装、启动和检查。

崩溃日志分析

# Recent crashes
ls -lt ~/Library/Logs/DiagnosticReports/*.crash | head -5

# Symbolicate a single address (if you have .dSYM)
xcrun atos -o YourApp.app.dSYM/Contents/Resources/DWARF/YourApp \
  -arch arm64 -l 0x100000000 0x<address>

# Symbolicate an entire crash log at once (LLDB Python script, may vary by Xcode version)
xcrun crashlog MyCrash.ips

常见错误

❌ 未检查环境就开始调试代码 — 始终先执行必需步骤

❌ 忽略模拟器状态 — “Booting” 可能卡住 10 多分钟，应立即关机并重启

❌ 认定问题由 git 更改导致 — 即使代码已更改，Derived Data 仍可能缓存旧构建

❌ 一个测试失败却运行完整测试套件 — 使用 -only-testing 隔离测试

实际效果

之前：花 30 多分钟调试“为什么运行的还是旧代码” 之后：2 分钟检查环境 → 清理 Derived Data → 问题解决

关键要点：先检查环境，再调试代码。