---
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="/zh-Hant/docs/codex/official/08-scenarios/102-swiftui-refactor" />
  <Card title="構建 iOS 應用" description="從 scaffold、build、debug 到 simulator loop 建立完整流程。" href="/zh-Hant/docs/codex/official/08-scenarios/109-ios-app" />
  <Card title="原生應用路線" description="按 iOS、macOS 和平臺工具鏈繼續學習。" href="/zh-Hant/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>
