使用案例 · iOS 模拟器调试

让 Codex 在 iOS Simulator 里复现并验证一个问题

用 XcodeBuildMCP 发现 Scheme 和模拟器，按固定操作重现故障，结合截图、日志和回溯收束到最小修复。

这次调试的产物包含复现脚本、目标 Scheme、模拟器与系统版本、修复前截图、相关日志或回溯、最小代码改动和修复后证据。验收者在同一模拟器条件下重新构建，按脚本操作，应能先看到旧问题，再在修复版本中得到预期结果。只看到编译成功，不能证明界面或崩溃问题已经解决。

确认机器和工具条件

这条流程需要 macOS、Xcode、已安装的 iOS Simulator 运行时和能够构建的工程。XcodeBuildMCP 当前说明要求 macOS 14.5 或更高、Xcode 16 系列或更高，使用 npm 安装时还需要 Node.js 18 或更高。版本会变化，安装前应再看项目说明。真机工具另需 Xcode 签名配置，本篇只处理模拟器。

在 ChatGPT 桌面端的 Codex 或 Codex CLI 中安装 Build iOS Apps 插件，或把 XcodeBuildMCP 作为 MCP 服务接入。Codex IDE 扩展当前不支持插件，IDE 用户应手动配置 MCP。插件会携带所需配置；手动接入时，除了默认 simulator workflow，还要按本次任务启用 ui-automation 与 debugging，重启连接后检查工具列表。工程还应给出依赖安装方式、工作区或项目文件、可用 Scheme、测试账号和故障描述。若问题依赖相机、蓝牙、推送、真机芯片或生产服务，模拟器可能不适合复现。

把原始报告改成动作脚本，写明初始数据、启动入口、每次点击或输入、故障出现位置、预期和实际。先不要让 Codex 改代码，目标是建立稳定基线。

测试账号和样例数据要能恢复。记录应用安装状态、系统语言、地区、文字大小、权限和网络条件。必要时复制一台干净模拟器作为基线，但不要随意清除仍需保留的调试数据。所有重置动作都写进复现脚本。

让 Codex 在 iOS Simulator 里复现并验证一个问题的入口、目标与准备条件操作示意图
图 1 · 进入任务前先确认目标、范围和准备条件

发现目标并建立基线

让 Codex 先列出工程、Scheme 和可用模拟器，选择与报告一致的运行时。清理只在确有缓存问题且得到同意时执行。先构建并启动应用，记录构建命令、应用标识、模拟器名称与系统版本。可见结果是应用能打开到已知初始页面，日志采集也已经开始。

随后让 XcodeBuildMCP 检查界面树，并按脚本执行点击、输入、滑动和等待。优先使用当前 runtime snapshot 里的 accessibility label、identifier 或 ref；导航、弹窗、搜索结果或布局一旦变化，就使用动作返回的新快照，或重新执行 snapshot_ui，不要复用旧 ref 或坐标。每个检查点保存截图，故障出现时同时保留当时界面树与日志。进程仍在运行但挂起时，可以直接附加 LLDB 取得线程和回溯。已经崩溃时要重新启动，并在下一次复现前附加。需要完整系统 crash report 时，先让调试器 detach，再由进程完成崩溃。不要在没有复现的情况下根据一段旧描述猜代码位置。

若第一次没有出现问题，逐项核对账号数据、系统权限、区域设置、动态字体、键盘、网络和启动方式。一次只改变一个条件。最终基线要么稳定复现，要么清楚写出仍缺少的真实条件，不能把“模拟器没有出现”写成问题已不存在。

日志采集要先限定进程、时间段和关心的子系统，减少系统噪声。截图和回溯可能含用户名、文件路径或请求内容，进入报告前应脱敏。若日志不足以支持判断，就保留原始文件路径和采集命令，不用推测填空。

复现失败本身也要记录条件和次数。它能帮助后续判断问题是否依赖时序或环境。

让 Codex 在 iOS Simulator 里复现并验证一个问题的三步关键操作与请求骨架示意图
图 2 · 把关键操作拆成三步，并给每一步留下可观察结果

从证据收束到最小改动

用日志时间点和界面状态定位最窄的代码路径。为每个假设写一个可推翻的检查，例如值是否为空、回调是否执行、状态更新是否在主线程、导航目标是否存在。先读相关调用者与已有测试，再选择能解释全部证据的假设。

改动只处理已证实路径，避免顺手重构相邻模块。能够抽成纯逻辑的问题先补测试，UI 时序或系统交互则保留模拟器复现作为验收。重新构建到同一模拟器，从相同初始数据开始按原脚本重走，比较截图、日志和回溯。还要执行一条邻近正常路径，确认修复没有破坏返回、保存或重新进入。

修复后停止日志采集，整理命令、代码差异、测试结果和前后证据。若问题只在某个系统版本消失，报告要保留该边界。需要真机确认的硬件或性能行为单独列出，不能用模拟器结果替代。

最后再关闭并重开应用，确认结果不依赖调试器附加状态或内存中的旧数据。崩溃问题要在调试器已按记录 detach 的条件下检查系统是否生成新的诊断记录，界面问题则在相同视口保存同一节点截图，避免用不同页面证明修复。

让 Codex 在 iOS Simulator 里复现并验证一个问题的结果验收与交付证据清单示意图
图 3 · 用结果、检查与交付证据确认任务真的完成

风险与限制

Simulator 的硬件、性能、通知、相机和后台行为与真机不同。调试器也会改变时序，偶发竞态可能在附加 LLDB 后消失。自动点击能重放给定路径，无法覆盖所有手势和系统状态。发布前仍要在目标真机和实际签名构建上复核关键问题。

交付清单

  1. macOS、Xcode、运行时和 XcodeBuildMCP 条件已记录
  2. Scheme、模拟器、应用版本和初始数据明确
  3. 修复前复现脚本、截图与日志可以重走
  4. 代码改动只覆盖证据支持的路径
  5. 同一脚本在修复后通过并检查邻近路径
  6. 真机仍需验证的限制已经列明

参考

  1. OpenAI iOS Simulator 调试用例
  2. OpenAI Build iOS Apps 插件
  3. Codex Plugins 说明
  4. Codex MCP 说明
  5. Codex Skills 说明
  6. XcodeBuildMCP 项目说明
  7. XcodeBuildMCP UI Automation
  8. Apple 在模拟器或设备上运行应用
  9. Apple 获取崩溃报告和诊断日志