Xcode 调试环境问题终极指南：解决构建失败、模拟器卡顿、SPM错误

axiom-xcode-debugging by charleswiltgen/axiom

209 周安装量

678 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/charleswiltgen/axiom --skill axiom-xcode-debugging

iOS 开发调试

🇨🇳中文介绍

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

强制性的首要步骤

务必首先运行这些命令（在阅读代码之前）：

# 1. 检查进程（有僵尸 xcodebuild 吗？）
ps aux | grep -E "xcodebuild|Simulator" | grep -v grep

# 2. 检查 Derived Data 大小（>10GB = 过期）
du -sh ~/Library/Developer/Xcode/DerivedData

# 3. 检查模拟器状态（卡在 Booting 状态？）
xcrun simctl list devices | grep -E "Booted|Booting|Shutting Down"

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

快速修复工作流

查找你的方案名称

如果你不知道你的方案名称：

# 列出可用方案
xcodebuild -list

针对过期的构建 / "No such module" 错误

# 清理所有内容
xcodebuild clean -scheme YourScheme
rm -rf ~/Library/Developer/Xcode/DerivedData/*
rm -rf .build/ build/

# 重新构建
xcodebuild build -scheme YourScheme \
  -destination 'platform=iOS Simulator,name=iPhone 16'

针对模拟器问题

# 关闭所有模拟器
xcrun simctl shutdown all

# 如果 simctl 命令失败，关闭并重试
xcrun simctl shutdown all
xcrun simctl list devices

# 如果仍然卡住，擦除特定模拟器
xcrun simctl erase <device-uuid>

# 终极方案：强制退出 Simulator.app
killall -9 Simulator

# 终止所有 xcodebuild 进程（谨慎使用）
killall -9 xcodebuild

# 检查它们是否已消失
ps aux | grep xcodebuild | grep -v grep

# 隔离失败的测试
xcodebuild test -scheme YourScheme \
  -destination 'platform=iOS Simulator,name=iPhone 16' \
  -only-testing:YourTests/SpecificTestClass

模拟器验证（可选）

应用修复后，在模拟器中进行验证，获取视觉确认。

# 1. 启动模拟器（如果尚未启动）
xcrun simctl boot "iPhone 16 Pro"

# 2. 构建并安装应用
xcodebuild build -scheme YourScheme \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro'

# 3. 启动应用
xcrun simctl launch booted com.your.bundleid

# 4. 等待 UI 稳定
sleep 2

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

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

/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

# 显示构建设置
xcodebuild -showBuildSettings -scheme YourScheme

# 列出方案/目标
xcodebuild -list

# 详细输出
xcodebuild -verbose build -scheme YourScheme

# 构建但不测试（更快）
xcodebuild build-for-testing -scheme YourScheme
xcodebuild test-without-building -scheme YourScheme

# 最近的崩溃
ls -lt ~/Library/Logs/DiagnosticReports/*.crash | head -5

# 符号化地址（如果你有 .dSYM）
atos -o YourApp.app.dSYM/Contents/Resources/DWARF/YourApp \
  -arch arm64 0x<address>

❌ 在检查环境之前调试代码 — 务必先运行强制步骤

❌ 忽略模拟器状态 — “Booting” 状态可能挂起 10 分钟以上，应立即关机/重启

❌ 假设是 git 更改导致的问题 — 尽管代码已更改，Derived Data 仍会缓存旧的构建

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

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

关键洞察 先检查环境，再调试代码。

🇺🇸English

Xcode Debugging

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.

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?"

→ The skill shows environment-first diagnostics: check Derived Data, simulator states, and zombie processes before investigating code

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

→ The skill explains stale Derived Data and intermittent failures, shows the 2-5 minute fix (clean 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."

→ The skill demonstrates that Derived Data caches old builds, shows how deletion forces a clean rebuild

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

→ The skill covers simulator state diagnosis with simctl and safe recovery patterns (erase/shutdown/reboot)

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

→ The skill explains SPM caching issues and the clean Derived Data workflow that resolves "phantom" module errors

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

Mandatory First Steps

ALWAYS run these commands FIRST (before reading code):

# 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"

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

Why environment first

Environment cleanup: 2-5 minutes → problem solved
Code debugging for environment issues: 30-120 minutes → wasted time

Quick Fix Workflow

Finding Your Scheme Name

If you don't know your scheme name:

# List available schemes
xcodebuild -list

For Stale Builds / "No such module" Errors

# 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'

For Simulator Issues

# 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

For Zombie Processes

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

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

For Test Failures

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

Simulator Verification (Optional)

After applying fixes, verify in simulator with visual confirmation.

Quick Screenshot Verification

# 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

Using Axiom Tools

Quick screenshot :

/axiom:screenshot

Full simulator testing (with navigation, state setup):

/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:

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

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

Useful Flags

# 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

Crash Log Analysis

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

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

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

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.

Weekly Installs

153

Repository

charleswiltgen/axiom

GitHub Stars

601

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode132

claude-code122

codex121

gemini-cli120

cursor114

github-copilot112

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

111,800 周安装