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

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

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

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/

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

If simctl command fails, shutdown and retry

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

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

终极方案：强制退出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

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"

2. Build and install app

2. 构建并安装应用

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

3. Launch app

3. 启动应用

xcrun simctl launch booted com.your.bundleid

4. Wait for UI to stabilize

4. 等待UI稳定

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

常见错误模式

Error	Fix
`BUILD FAILED` (no details)	Delete Derived Data
`Unable to boot simulator`	`xcrun simctl erase <uuid>`
`No such module`	Clean + delete Derived Data
Tests hang	Check simctl list, reboot simulator
Stale code executing	Delete 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

List schemes/targets

列出Scheme/目标

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

undefined

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

undefined

Crash Log Analysis

崩溃日志分析

bash

undefined

bash

undefined

Recent crashes

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 → 问题解决

关键见解：先检查环境，再调试代码。