---
title: "在 iOS 模拟器里复现和修 Bug"
description: "说明用 Codex 调试 iOS bug 时，如何建立 simulator loop、收集证据、修改代码并复现验证。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

用 Codex 调 iOS bug，最好让它拥有完整 simulator loop：选择 app target，启动 Simulator，检查当前屏幕，执行复现路径，收集 logs 和 screenshots，需要时看 stack trace，修改代码，再跑同一路径验证修复。

> [!IMPORTANT]
> iOS 调试先要证据，再改代码。让 Codex 记录 simulator、scheme、复现步骤、截图、日志或 stack trace，否则修复很难 review。

官方页面：[https://developers.openai.com/codex/use-cases/ios-simulator-bug-debugging](https://developers.openai.com/codex/use-cases/ios-simulator-bug-debugging)

## 适合什么任务

| 场景 | Codex 应该做什么 |
|---|---|
| bug 只在特定 tap、scroll、form entry 后出现 | 用 Simulator 真实执行复现路径 |
| crash、hang、broken navigation 需要证据 | 收集 logs、screenshots、view hierarchy、LLDB backtrace |
| 团队希望 Codex 跑完整 reproduce-fix-verify loop | 自己复现、定位、修复，再重新验证 |

## 使用的能力

| 能力 | 用法 | 链接 |
|---|---|---|
| `build-ios-apps` | 用 iOS debugger agent 通过 XcodeBuildMCP build、launch、inspect、drive Simulator，并收集 logs、screenshots、stack traces | [https://github.com/openai/plugins/tree/main/plugins/build-ios-apps](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) |

相关官方说明：

- Build iOS Apps plugin：[https://github.com/openai/plugins/tree/main/plugins/build-ios-apps](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps)
- Model Context Protocol：[https://developers.openai.com/codex/mcp](https://developers.openai.com/codex/mcp)
- Agent skills：[https://developers.openai.com/codex/skills](https://developers.openai.com/codex/skills)

## 起始提示词

```text
请使用 Build iOS Apps plugin 和 XcodeBuildMCP，直接在 Simulator 中复现这个 bug，诊断 root cause，并实现一个小修复。

Bug report：
[描述 expected behavior、actual bug，以及任何已知 screen 或 account setup。]

约束：
- 先检查 project、scheme 和 simulator 是否已经选定。如果没有，请发现正确的 Xcode project 或 workspace，选择 app scheme，选择 simulator，并在本 session 后续复用这套 setup。
- 在 Simulator 中 build 并 launch app；开始交互前，先用 UI snapshot 或 screenshot 确认正确 screen 可见。
- 自己在 simulator 里通过 tapping、typing、scrolling 和 swiping 执行准确复现路径。优先使用 accessibility labels 或 IDs，不要依赖 raw coordinates；layout 变化后，下一步操作前重新读取 UI hierarchy。
- 调试时捕获证据：visual state 用 screenshots，failure 附近用 simulator logs；如果像 crash 或 hang，再收集 LLDB stack frames 或 variables。
- 如果 simulator 尚未 boot，请 boot 一个，并告诉我选择了哪个 device 和 OS。如果需要 credentials 或特殊 fixture，暂停并只询问这个缺失输入。
- 做能解决 bug 的最小代码改动，然后重新运行 simulator flow，并准确说明你如何验证修复。

交付：
- Codex 执行的 reproduction steps
- 解释 bug 的关键 screenshots、logs 或 stack details
- code fix 以及它为什么有效
- 最终验证使用的 simulator 和 scheme
```

这个 prompt 要求 Codex 先复现和收集证据，再改代码。不要让它跳过 simulator evidence 直接猜修复。

## 推荐技术面

| 需要 | 推荐默认值 | 原因 |
|---|---|---|
| Simulator automation | [XcodeBuildMCP](https://www.xcodebuildmcp.com/) | 覆盖 simulator setup、build/launch、UI snapshots、taps、typing、gestures、screenshots、log capture、debugger attachment |
| Agent workflow | [Build iOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-ios-apps) | iOS debugger agent 提供 simulator-first loop，用于复现 bug、收集证据、验证修复 |
| App observability | `Logger`、`OSLog`、LLDB、Simulator screenshots | Codex 可以用 logs 和 debugger state 解释问题，并保存修复前后的 UI evidence |

## 给 Codex 完整 Simulator Loop

这个用例最适合让 Codex 按完整链路工作：

1. 发现 Xcode project 或 workspace。
2. 选择 app scheme。
3. 选择或启动 simulator。
4. build、install、launch app。
5. 读取 UI accessibility hierarchy。
6. 按复现步骤 tap、type、scroll、swipe。
7. 收集 screenshots、simulator logs、LLDB stack frames。
8. 修改最小代码。
9. 重新运行同一路径验证。

如果 Codex 还没选定 project、scheme 和 simulator，先让它 discover，并在后续 session 复用这个 setup。

## XcodeBuildMCP 能做什么

实用 capability groups：

- **Project and simulator discovery**：检查 app target 和 simulator，发现 Xcode project/workspace，枚举 schemes，找到或启动 simulator。
- **Build and launch control**：build active app target，安装并启动 simulator build，需要时 relaunch with log capture，解析 app bundle id。
- **UI inspection and interaction**：读取 accessibility hierarchy，截图，tap controls，type fields，scroll lists，执行 edge swipes 或其他 gestures。
- **Logs and debugger state**：stream simulator logs，attach LLDB，set breakpoints，检查 stack frames 和 local variables，执行 debugger commands。

关键习惯：tap 前先 inspect view tree。优先用 accessibility labels 或 IDs，不要猜 raw screen coordinates。

## 实用建议

### 要 evidence，不只要 fix

要求 Codex 回报 exact simulator、scheme、screenshots、log snippets 和 stack details。这样最终 patch 比一句 “I think this should fix it” 更可 review。

### 优先 accessibility labels

如果 Codex 必须用坐标 tap，因为控件没有 stable label 或 accessibility identifier，让它指出来。这通常也说明修复可以顺手补一个 UI testability improvement。

### 一次只修一个 bug

Simulator-driven debugging 很强，但可信度来自闭环。一个 prompt 聚焦一个 failure mode，先完成一轮 reproduce-fix-verify，再扩展到相邻问题。

## 接下来去哪

<Cards>
  <Card title="SwiftUI 重构" description="修复后需要保持行为不变地拆分复杂 screen。" href="/docs/codex/official/08-scenarios/102-swiftui-refactor" />
  <Card title="构建 iOS 应用" description="从 scaffold、build、debug 到 simulator loop 建立完整流程。" href="/docs/codex/official/08-scenarios/109-ios-app" />
  <Card title="原生应用路线" description="按 iOS、macOS 和平台工具链继续学习。" href="/docs/codex/official/07-learning-paths/77-native-app-path" />
  <Card title="官方 iOS simulator use case" description="XcodeBuildMCP 和插件说明以官方页面为准。" href="https://developers.openai.com/codex/use-cases/ios-simulator-bug-debugging" />
</Cards>
