Back to Details

axiom-xcode-debugging

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Xcode Debugging

Xcode调试

Overview

概述

Check build environment BEFORE debugging code. Core principle 80% of "mysterious" Xcode issues are environment problems (stale Derived Data, stuck simulators, zombie processes), not code bugs.
在调试代码之前先检查构建环境。核心原则：80%的“莫名”Xcode问题都是环境问题（过期的Derived Data、卡住的模拟器、僵尸进程），而非代码bug。

Example Prompts

示例提问

These are real questions developers ask that this skill is designed to answer:
以下是开发者实际会问的问题，本技能正是为解答这些问题设计的：

1. "My build is failing with 'BUILD FAILED' but no error details. I haven't changed anything. What's going on?"

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

→ The skill shows environment-first diagnostics: check Derived Data, simulator states, and zombie processes before investigating code
→ 本技能会展示优先排查环境的诊断步骤：在排查代码之前，先检查Derived Data、模拟器状态和僵尸进程

2. "Tests passed yesterday with no code changes, but now they're failing. This is frustrating. How do I fix this?"

2. “昨天测试还通过了，我没改代码，但今天测试失败了。这太让人沮丧了，我该怎么修复？”

→ The skill explains stale Derived Data and intermittent failures, shows the 2-5 minute fix (clean Derived Data)
→ 本技能会解释Derived Data过期和间歇性失败的问题，展示2-5分钟即可完成的修复方法（清理Derived Data）

3. "My app builds fine but it's running the old code from before my changes. I restarted Xcode but it still happens."

3. “我的应用构建成功了，但运行的是我修改前的旧代码。我重启了Xcode但还是这样。”

→ The skill demonstrates that Derived Data caches old builds, shows how deletion forces a clean rebuild
→ 本技能会说明Derived Data会缓存旧构建产物，展示如何通过删除它来强制重新构建

4. "The simulator says 'Unable to boot simulator' and I can't run tests. How do I recover?"

4. “模拟器显示‘Unable to boot simulator’，我无法运行测试。该怎么恢复？”

→ The skill covers simulator state diagnosis with simctl and safe recovery patterns (erase/shutdown/reboot)
→ 本技能涵盖使用simctl诊断模拟器状态的方法，以及安全恢复的模式（擦除/关闭/重启）

5. "I'm getting 'No such module: SomePackage' errors after updating SPM dependencies. How do I fix this?"

5. “我更新SPM依赖后出现了‘No such module: SomePackage’错误，该怎么修复？”

→ The skill explains SPM caching issues and the clean Derived Data workflow that resolves "phantom" module errors
→ 本技能会解释SPM缓存问题，以及通过清理Derived Data解决“幽灵”模块错误的流程

Red Flags — Check Environment First

危险信号——优先检查环境

If you see ANY of these, suspect environment not code:
  • "It works on my machine but not CI"
  • "Tests passed yesterday, failing today with no code changes"
  • "Build succeeds but old code executes"
  • "Build sometimes succeeds, sometimes fails" (intermittent failures)
  • "Simulator stuck at splash screen" or "Unable to install app"
  • Multiple xcodebuild processes (10+) older than 30 minutes
如果你遇到以下任何一种情况，先怀疑环境问题而非代码问题：
  • “在我本地能运行，但CI上不行”
  • “昨天测试通过，今天没改代码但测试失败”
  • “构建成功但运行的是旧代码”
  • “构建有时成功有时失败”（间歇性失败）
  • “模拟器卡在启动页”或“无法安装应用”
  • 存在10个以上运行时长超过30分钟的xcodebuild进程

Mandatory First Steps

必须先执行的步骤

ALWAYS run these commands FIRST (before reading code):
bash
undefined
在查看代码之前，务必先运行以下命令：
bash
undefined

1. Check processes (zombie xcodebuild?)

1. 检查进程（是否有僵尸xcodebuild？）

ps aux | grep -E "xcodebuild|Simulator" | grep -v grep
ps aux | grep -E "xcodebuild|Simulator" | grep -v grep

2. Check Derived Data size (>10GB = stale)

2. 检查Derived Data大小（超过10GB即为过期）

du -sh ~/Library/Developer/Xcode/DerivedData
du -sh ~/Library/Developer/Xcode/DerivedData

3. Check simulator states (stuck Booting?)

3. 检查模拟器状态（是否卡在Booting状态？）

xcrun simctl list devices | grep -E "Booted|Booting|Shutting Down"
undefined
xcrun simctl list devices | grep -E "Booted|Booting|Shutting Down"
undefined

What these tell you

这些命令能告诉你什么

  • 0 processes + small Derived Data + no booted sims → Environment clean, investigate code
  • 10+ processes OR >10GB Derived Data OR simulators stuck → Environment problem, clean first
  • Stale code executing OR intermittent failures → Clean Derived Data regardless of size
  • 0个进程 + 小体积Derived Data + 无已启动模拟器 → 环境正常，排查代码问题
  • 10个以上进程 或 Derived Data超过10GB 或 模拟器卡住 → 环境问题，先清理环境
  • 运行旧代码 或 间歇性失败 → 无论大小，都要清理Derived Data

Why environment first

为什么优先检查环境

  • Environment cleanup: 2-5 minutes → problem solved
  • Code debugging for environment issues: 30-120 minutes → wasted time
  • 环境清理：2-5分钟 → 问题解决
  • 针对环境问题调试代码：30-120分钟 → 浪费时间

Quick Fix Workflow

快速修复流程

Finding Your Scheme Name

查找你的Scheme名称

If you don't know your scheme name:
bash
undefined
如果你不知道自己的Scheme名称：
bash
undefined

List available schemes

列出可用的Scheme

xcodebuild -list
undefined
xcodebuild -list
undefined

For Stale Builds / "No such module" Errors

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

bash
undefined
bash
undefined

Clean everything

清理所有内容

xcodebuild clean -scheme YourScheme rm -rf ~/Library/Developer/Xcode/DerivedData/* rm -rf .build/ build/
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'
undefined
xcodebuild build -scheme YourScheme
-destination 'platform=iOS Simulator,name=iPhone 16'
undefined

For Simulator Issues

针对模拟器问题

bash
undefined
bash
undefined

Shutdown all simulators

关闭所有模拟器

xcrun simctl shutdown all
xcrun simctl shutdown all

If simctl command fails, shutdown and retry

如果simctl命令失败，关闭后重试

xcrun simctl shutdown all xcrun simctl list devices
xcrun simctl shutdown all xcrun simctl list devices

If still stuck, erase specific simulator

如果仍然卡住，擦除特定模拟器

xcrun simctl erase <device-uuid>
xcrun simctl erase <device-uuid>

Nuclear option: force-quit Simulator.app

终极方案：强制退出Simulator.app

killall -9 Simulator
undefined
killall -9 Simulator
undefined

For Zombie Processes

针对僵尸进程

bash
undefined
bash
undefined

Kill all xcodebuild (use cautiously)

杀死所有xcodebuild进程（谨慎使用）

killall -9 xcodebuild
killall -9 xcodebuild

Check they're gone

检查是否已全部清除

ps aux | grep xcodebuild | grep -v grep
undefined
ps aux | grep xcodebuild | grep -v grep
undefined

For Test Failures

针对测试失败

bash
undefined
bash
undefined

Isolate failing test

隔离失败的测试

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

Simulator Verification (Optional)

模拟器验证（可选）

After applying fixes, verify in simulator with visual confirmation.
应用修复后，通过可视化确认来验证模拟器状态。

Quick Screenshot Verification

快速截图验证

bash
undefined
bash
undefined

1. Boot simulator (if not already)

1. 启动模拟器（如果未启动）

xcrun simctl boot "iPhone 16 Pro"
xcrun simctl boot "iPhone 16 Pro"

2. Build and install app

2. 构建并安装应用

xcodebuild build -scheme YourScheme
-destination 'platform=iOS Simulator,name=iPhone 16 Pro'
xcodebuild build -scheme YourScheme
-destination 'platform=iOS Simulator,name=iPhone 16 Pro'

3. Launch app

3. 启动应用

xcrun simctl launch booted com.your.bundleid
xcrun simctl launch booted com.your.bundleid

4. Wait for UI to stabilize

4. 等待UI稳定

sleep 2
sleep 2

5. Capture screenshot

5. 捕获截图

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

Using Axiom Tools

使用Axiom工具

Quick screenshot:
bash
/axiom:screenshot
Full simulator testing (with navigation, state setup):
bash
/axiom:test-simulator
快速截图:
bash
/axiom:screenshot
完整模拟器测试（包含导航、状态设置）:
bash
/axiom:test-simulator

When to Use Simulator Verification

何时使用模拟器验证

Use when:
  • Visual fixes — Layout changes, UI updates, styling tweaks
  • State-dependent bugs — "Only happens in this specific screen"
  • Intermittent failures — Need to reproduce specific conditions
  • Before shipping — Final verification that fix actually works
Pro tip: If you have debug deep links (see 
axiom-deep-link-debugging
skill), you can navigate directly to the screen that was broken:
bash
xcrun simctl openurl booted "debug://problem-screen"
sleep 1
xcrun simctl io booted screenshot /tmp/fix-verification.png
在以下场景使用：
  • 可视化修复 — 布局变更、UI更新、样式调整
  • 依赖状态的bug — “只在这个特定页面出现问题”
  • 间歇性失败 — 需要复现特定条件
  • 发布前 — 最终验证修复是否真的有效
专业提示：如果你有调试深度链接（查看
axiom-deep-link-debugging
技能），可以直接导航到出问题的页面：
bash
xcrun simctl openurl booted "debug://problem-screen"
sleep 1
xcrun simctl io booted screenshot /tmp/fix-verification.png

Decision Tree

决策树

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 → 重新构建
├─ 构建间歇性失败（有时成功有时失败）？
│  └─ 清理Derived Data → 重新构建
├─ 构建成功但运行旧代码？
│  └─ 删除Derived Data → 重新构建（2-5分钟修复）
├─ 出现“Unable to boot simulator”错误？
│  └─ 执行xcrun simctl shutdown all → 擦除模拟器
├─ 出现“No such module PackageName”错误？
│  └─ 清理并删除Derived Data → 重新构建
├─ 测试无限期挂起？
│  └─ 检查simctl列表 → 重启模拟器
├─ 测试崩溃？
│  └─ 查看~/Library/Logs/DiagnosticReports/*.crash
└─ 代码逻辑bug？
   └─ 改用systematic-debugging技能

Common Error Patterns

常见错误模式

ErrorFix
BUILD FAILED
(no details)		Delete Derived Data
Unable to boot simulator
xcrun simctl erase <uuid>
No such module
Clean + delete Derived Data
Tests hangCheck simctl list, reboot simulator
Stale code executingDelete Derived Data
错误修复方法
BUILD FAILED
（无详情）		删除Derived Data
Unable to boot simulator
xcrun simctl erase <uuid>
No such module
清理并删除Derived Data
测试挂起检查simctl列表，重启模拟器
运行旧代码删除Derived Data

Useful Flags

实用参数

bash
undefined
bash
undefined

Show build settings

显示构建设置

xcodebuild -showBuildSettings -scheme YourScheme
xcodebuild -showBuildSettings -scheme YourScheme

List schemes/targets

列出Scheme/目标

xcodebuild -list
xcodebuild -list

Verbose output

详细输出

xcodebuild -verbose build -scheme YourScheme
xcodebuild -verbose build -scheme YourScheme

Build without testing (faster)

只构建不测试（更快）

xcodebuild build-for-testing -scheme YourScheme xcodebuild test-without-building -scheme YourScheme
undefined
xcodebuild build-for-testing -scheme YourScheme xcodebuild test-without-building -scheme YourScheme
undefined

Crash Log Analysis

崩溃日志分析

bash
undefined
bash
undefined

Recent crashes

最近的崩溃日志

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

Symbolicate address (if you have .dSYM)

符号化地址（如果有.dSYM文件）

atos -o YourApp.app.dSYM/Contents/Resources/DWARF/YourApp
-arch arm64 0x<address>
undefined
atos -o YourApp.app.dSYM/Contents/Resources/DWARF/YourApp
-arch arm64 0x<address>
undefined

Common Mistakes

常见错误

❌ Debugging code before checking environment — Always run mandatory steps first
❌ Ignoring simulator states — "Booting" can hang 10+ minutes, shutdown/reboot immediately
❌ Assuming git changes caused the problem — Derived Data caches old builds despite code changes
❌ Running full test suite when one test fails — Use 
-only-testing
to isolate
❌ 先调试代码再检查环境 — 务必先执行必须的步骤
❌ 忽略模拟器状态 — “Booting”状态可能会挂起10分钟以上，立即关闭/重启
❌ 假设是git变更导致的问题 — 即使代码变更，Derived Data仍可能缓存旧构建产物
❌ 一个测试失败却运行整个测试套件 — 使用
-only-testing
参数隔离问题测试用例

Real-World Impact

实际效果

Before 30+ min debugging "why is old code running" After 2 min environment check → clean Derived Data → problem solved
Key insight Check environment first, debug code second.
之前：花30多分钟调试“为什么运行的是旧代码” 之后：2分钟环境检查 → 清理Derived Data → 问题解决
关键见解：先检查环境，再调试代码。