ios-issue-fix

name	ios-issue-fix
description	Guides iOS issue diagnosis and fix through a five-phase methodology from understanding the issue to verified fix. Use when fixing bugs, crashes, UI anomalies, performance issues, or any unexpected behavior in iOS applications.

iOS Issue 修复

核心原则

先读懂问题，再理解上下文，后动代码，改完必审查。

大多数 Bug 不是崩溃，而是"功能没按预期工作"。修复的关键是理解预期行为与实际行为的差异，以及这个差异在代码中是如何产生的。

修复前必须回答的 4 个问题

1. 预期行为是什么？ — 产品/设计/用户期望看到什么结果
2. 实际行为是什么？ — 现在实际发生了什么
3. 差异在哪里产生？ — 代码中哪个环节导致了偏差
4. 改动会不会波及其他地方？ — 这段代码还被谁依赖

绝对禁止

• Issue 描述没读完就开始改代码
• 不理解原有代码的意图就直接修改
• 不检查修复对其他模块的影响就提交 PR
• 用 try! / ! / asyncAfter / 空 catch {} 掩盖问题

---

复杂度速判

在进入五阶段流程前，先快速评估问题复杂度，决定走完整流程还是精简流程：

级别	判断标准	流程路径	典型场景
S — 简单	根因明显、影响范围单一、改动 < 10 行	阶段一 → 阶段四 → 阶段五	拼写错误、硬编码值修正、简单的 UI 微调
M — 中等	需要排查定位、涉及 2-3 个文件、有上下游依赖	完整五阶段流程	状态管理 Bug、数据展示异常、导航流程错误
L — 复杂	涉及多模块/跨层/并发/架构层问题、复现困难	完整五阶段流程 + 额外评审	偶现崩溃、性能退化、多线程数据竞争

特别规则： 崩溃类问题一律按 M 级及以上 处理，即使看起来简单。崩溃的影响范围往往比表面更广。

---

五阶段流程

阶段一：阅读与理解问题

从 Issue 描述中提取"预期 vs 实际"差异。对问题进行 7 大类分类，明确复现条件，输出"问题理解卡片"。如果无法写出清晰的卡片，说明 Issue 还没读懂，不要开始下一步。

详细模板与追问清单 → references/issue-classification.md

门控输出： 完成「问题理解卡片」，包含预期/实际行为、分类、复现路径。无法写出清晰卡片则不进入下一阶段。

阶段二：项目上下文关联分析

定位问题涉及的代码范围，理解原有代码的设计意图。按问题类型选择不同定位策略，用 5 步检查法理解代码意图，通过 Git 历史追溯变更原因，输出"影响范围图"。

定位策略、5 步检查法、Git 命令与影响范围图 → references/root-cause-analysis.md

门控输出： 完成「影响范围图」，包含问题文件/函数、上下游依赖、关联组件。影响范围不清楚则不进入下一阶段。

阶段三：根因定位

找到导致差异的精确代码位置和原因。按问题类型选择对应排查策略，SwiftUI 问题参考专项指南，最终用一句话描述根因："因为 X，导致 Y，所以用户看到了 Z"。

分类型排查策略 → references/debug-by-type.md SwiftUI 专项排查 → references/swiftui-debugging.md Xcode 调试工具速查 → references/xcode-tools.md

门控输出： 完成「根因一句话描述」。说不出"因为 X → 导致 Y → 用户看到 Z"则说明根因未定位，不进入修复阶段。

阶段四：实现修复

针对根因实现最小、安全、可测试的修复。遵循最小修改原则、在根因处修复、保持原有代码风格、使用 Swift 安全修复模式。为 Bug 编写"先红后绿"的测试。

修复原则、安全模式与测试选型 → references/fix-patterns.md

门控输出： 修复代码已实现 + Bug 场景测试已通过（先红后绿）。测试未通过则不进入审查阶段。

阶段五：修复审查与影响评估

确保修复有效且不引入新问题。完成代码自审清单，进行 5 层影响范围验证，按多维度（设备/系统/模式/网络/构建）验证，按规范提交 PR。

自审清单、5 层验证与 PR 模板 → references/verification.md

门控输出： 自审清单全部通过 + 影响范围验证完成 + PR 已按规范提交。

---

Topic Router — 问题类型导航

问题类型	主要参考文件	辅助参考
UI 显示异常	debug-by-type.md → UI 显示异常	xcode-tools.md（View Debugger）
SwiftUI 视图不更新	swiftui-debugging.md → 视图不更新	debug-by-type.md → 数据不更新
SwiftUI 性能问题	swiftui-debugging.md → 性能问题	xcode-tools.md（Instruments）
SwiftUI 导航问题	swiftui-debugging.md → 导航问题	debug-by-type.md → 交互异常
功能逻辑错误	debug-by-type.md → 功能逻辑错误	root-cause-analysis.md
数据问题	debug-by-type.md → 数据问题	xcode-tools.md（抓包/LLDB）
交互异常	debug-by-type.md → 交互不符合预期	swiftui-debugging.md → 动画问题
兼容性问题	debug-by-type.md → 兼容性问题	verification.md → 多维度验证
崩溃	debug-by-type.md → 崩溃	xcode-tools.md（Zombie/ASan）
线上崩溃 / 崩溃符号化 / 崩溃日志解读	crash-analysis.md	debug-by-type.md → 崩溃
网络请求失败 / HTTP 错误 / Codable 解析 / SSL	network-debugging.md	debug-by-type.md → 数据问题
性能问题	xcode-tools.md（Time Profiler）	swiftui-debugging.md → 性能

---

输出格式规范

修复流程中需产出以下三个关键输出：

问题理解卡片（阶段一输出）

问题：[用自己的话复述问题，不超过两句]
预期：[应该怎样]  实际：[现在怎样]
分类：[7 类之一]  严重程度：[P0-P3]
复现路径：[步骤 1 → 步骤 2 → 出现问题]

影响范围图（阶段二输出）

文件：[路径:行号]  函数：[函数名]
上游：[调用方列表]  下游：[依赖列表]
关联组件：[可能波及的组件 + 原因]

根因一句话描述（阶段三输出）

因为 [X 根因]，导致 [Y 直接后果]，所以用户看到了 [Z 现象]

---

深层问题警告信号

以下情况说明不是简单 Bug，需要暂停讨论：

信号	含义	应对
修复 A 页面导致 B 页面出问题	状态管理存在全局耦合	讨论状态管理方案重构
同一 Bug 在多个页面重复出现	公共组件或基础逻辑有缺陷	修复公共层而非逐页面打补丁
修复需要在 10+ 处添加相同 guard let	数据流设计有缺陷	重新设计数据流
每次修 Bug 都暴露新的隐藏 Bug	技术债积累过多	安排技术债清理
连续三次修复尝试均失败	对问题理解可能是错的	回到阶段一重新理解问题

此时应立即停止打补丁，记录所有关联问题，评估是否需要架构优化，与团队讨论修复策略。如需重构，单独排期，不在 Bug 修复 PR 中混入。

---

何时停止修复尝试

以下任一条件满足时，应停止当前修复尝试并升级处理：

退出条件	触发标准	下一步行动
修复尝试次数超限	连续 3 次修复尝试均未解决问题	回到阶段一重新理解问题，考虑是否误判了根因
影响范围不可控	修复导致 2 个以上新问题出现	回退修改，重新评估影响范围，必要时拉其他开发者评审
超出能力边界	涉及不熟悉的底层框架/第三方 SDK 内部问题	记录已知信息，升级给领域专家或联系 SDK 提供方
问题无法复现	投入 > 2 小时仍无法稳定复现	添加详细日志埋点，等待下次复现时收集信息
需要架构变更	修复方案需要改动 5+ 个文件或跨 3+ 个模块	转为技术方案评审，单独排期，不在 Bug 修复中混入
时间投入过高	排查时间超过预期的 3 倍仍无进展	暂停并记录当前进展，寻求团队协助或换人排查

---

红旗信号表

违规行为	为什么是错误的	正确做法
Issue 没读完就改代码	理解偏差导致修错方向	完成问题理解卡片
不看原有代码直接改	破坏原有设计意图	完成上下文分析
在 UI 层修数据层的问题	根因未修复，其他页面仍有问题	追溯到根因所在层修复
修完不验证波及面	修一个 Bug 引入两个新 Bug	完成影响范围验证
用 asyncAfter 修时序问题	不同设备速度不同，治标不治本	找到正确的生命周期事件点
用 try! / ! 消除警告	运行期崩溃比编译期警告更危险	用 guard let / if let / ??
空 catch {} 吞异常	丢失错误信息，排查无据可依	catch 中至少记录日志
"模拟器上好了"就结束	真机行为可能完全不同	真机验证为最终标准
改了公共组件不验其他调用方	影响面可能远超预期	全局搜索所有调用方逐一验证
没写测试就提 PR	无法防止未来回归	先红后绿，覆盖 Bug 场景

---

修复完成清单

维度	检查项
问题	能用一句话解释根因 / 复现路径验证通过 / 预期行为验证通过
代码	修复针对根因 / 范围最小化 / 无强制解包和空 catch / 遵循项目风格
测试	已编写覆盖 Bug 场景的测试 / 完整测试套件通过 / 真机验证通过
影响	同页面验证 / 上下游页面验证 / 公共代码调用方验证 / Dark Mode+多屏验证

---

与其他 Skill 的协作

• ios-feature-impl：修复过程中发现需求理解偏差时，回到需求阅读流程
• code-review：修复 PR 的审查流程