做半导体,也做 iOS App:我把“调试”这件事重新学了一遍

白天做半导体项目，晚上做自己的 iOS App，我原以为只是换了一套工具。真正让我停下来的，却是两个很小的问题：一个页面进入了 mock fallback；一个 App 图标在编辑器里和归档产物里看起来不完全一样。

它们都没有惊天动地的根因。甚至到今天，其中一个问题仍没有足够证据让我宣布“已经定位”。但这两次记录把我从一个坏习惯里拽了出来：看到异常后立刻解释，连续改几处，等界面恢复正常，再把最后一次操作当成答案。

现在我更看重的不是“修好了”三个字，而是下一次能不能复现、能不能回退、能不能说清哪条证据支持哪一步。

这篇只拆我自己保留下来的 iOS 证据。没有保存的设备信息、操作时间线和修复前截图，我不会用顺滑的叙事补齐。

页面告诉我的第一件事：先确认走了哪条路径

一次真机检查里，设置页显示了两行很直接的状态：Mock fallback active，以及 Apple Foundation Models 在当前设备或配置上不可用。

这张图能确认什么？当前运行没有走目标框架，而是进入了回退路径。它还把“设备或配置”列为范围，却没有替我区分究竟是哪一种。

它能证明路径，不能证明根因。

这一区别看着细，实际会决定后面半小时怎么花。如果我把截图直接翻译成“某段业务代码坏了”，下一步多半会去改调用逻辑。可页面已经给出另一条更靠前的检查顺序：先核对设备能力、系统条件和构建配置，再谈业务逻辑。

当时留下的公开安全证据不包含具体机型、系统版本，也没有一条从启动到进入设置页的完整时间线。于是这次记录只能停在“已识别运行路径，根因未关闭”。这个结论不漂亮，却比猜一个答案有用。

我后来把它整理成一份已填写的最小记录：

“未知”不是空白项。把未知写出来，才知道下一次要补什么。

把一句“坏了”拆成三层

我以前写问题记录，常把观察和判断塞在同一句话里，例如“本地模型不可用，所以回退代码有问题”。这句话看似简洁，其实混了三件事：页面显示了什么、我猜原因是什么、下一步准备查什么。只要前半句成立，后半句就容易被误当成事实。

现在我会强迫自己分三层写。

第一层是观察：设置页出现 Mock fallback active。这句话可以由截图直接核对。

第二层是解释范围：页面提示目标框架在当前设备或配置上不可用。这里仍有两个分支，设备能力与配置条件，尚未区分。

第三层才是动作：先补设备与系统信息，核对构建配置；这两项没完成前，不改业务调用。

这样写还有一个好处。别人接手时，不必先判断我的猜测是否可靠。他能从第一层重新出发，沿着仍未关闭的分支继续查。交接最怕的不是信息少，而是猜测和事实长得一模一样。

如果后面发现页面文案本身有误，第一层也能单独被推翻，不会拖着整条故事一起重写。这就是我现在理解的“可复查”：不是文档写得多，而是每一句都有清楚的来源和状态。

一次改动应该回答一个问题

另一个问题来自 App 图标。手头保留下来的最终配置很简单：只有一个 Hero 图层，并且关闭了 translucency。

{   "layers": [     { "image-name": "hero.png", "name": "Hero" }   ],   "translucency": {     "enabled": false,     "value": 0.0   } } 

我重新打开自有工程里的 AppIcon 配置，在 Xcode 中核对到的就是这组最终字段：Hero 单层输入，translucency.enabled=false。

这张截图能确认配置文件此刻声明了什么，也能和上面的文本记录互相核对。它不能证明这份配置已经覆盖全部构建目标，更不能证明关闭透明效果就是旧异常的唯一原因。

对应的源资产是一张完整的狐狸图；归档里也保留了 build 9 的 AppIcon60x60@2x 编译产物。它们只有 120×120 像素，不作为正文“真实截图数”凑数，只留在内部证据登记里核对输入与归档内容。

我还保留了一张独立的模拟器运行验收图。它来自自有项目的另一轮 UI 检查，可以证明 App 当时能在模拟器里启动并进入首页；它不是 build 9 的系统桌面截图，也不能替图标问题补出缺失的前后对照。

把这三份材料放在一起，我可以说：最终配置引用单层 Hero，透明效果关闭；build 9 的归档里确实有对应的狐狸图标产物。

我不能据此说，关闭透明效果就是此前视觉异常的唯一根因。

原因很朴素：修复前的真机图没有进入这组安全证据，逐轮配置差异也没有完整保留。现在只剩最终输入、最终配置和一个 120×120 的归档结果。它们适合证明“最后交付了什么”，不适合倒推出“前面每一步为什么失败”。

过去我很容易在这里写出一个完整故事：先用了某种图层，编译后变灰；改掉某项配置，颜色恢复；于是根因关闭。读起来很顺，证据却少了中间两块。调试文章最危险的润色，是把时间先后写成因果。

所以这次我把结论缩短了。最终配置是一个可复查锚点，归档产物是另一个锚点。至于系统桌面上的浅色、深色显示，以及不同尺寸的实际效果，还需要新的真机截图才能验收。

这组材料也让我重新区分了“配置正确”和“结果通过”。配置文件可以被语法检查，也可以确认引用了存在的资源；归档产物可以核对像素尺寸和主体内容；系统呈现却受构建、安装与界面环境影响。三者不是同一个测试。

如果只检查配置，我会把结论写成“工程声明了什么”。如果检查到归档，我会写“这个构建包含什么”。只有安装到目标设备、在约定环境里观察后，才可以写“用户实际看到什么”。证据层级往前走一格，结论才能跟着走一格。

编辑器预览不是交付物

做界面时，编辑器里“看起来对了”很有诱惑力。图标问题尤其如此：源图清楚、预览鲜艳，很容易让人提前结束检查。

真正进入 App 的却是构建链处理后的资产。它可能经过尺寸选择、压缩、图层合成和系统呈现。源图只能说明输入，工程配置说明处理方式，归档文件说明某个构建包含了什么。最后还要看真机上的实际显示。

我现在会把输入、配置、编译产物和真机结果分成四个格子。少一格，就把结论停在那一格。

这次已有前三格中的大部分材料，但第四格不完整。120×120 的归档图标不能替代系统桌面，也不能覆盖所有尺寸。把缺口写在文章里，不是自我拆台。它让下一轮验收有明确任务：补浅色与深色桌面截图，记录系统版本，确认安装的确是同一构建。

日志要和动作排在同一条时间线上

截图经常被单独扔进一个文件夹，文件名叫“成功”“最终版”或者“真的最终版”。过一周再看，谁也说不清它对应哪次构建。

我现在更愿意保留一条很短的时间线：何时复现、当时是什么构建、只改了什么、看到什么、是否回退。一次尝试不必写成长报告，五六行就够。

负结果也要留着。“换了配置仍然进入 fallback”“源图替换后归档产物没变化”这类记录，会关闭一条错误方向。只保存最后那张好看的截图，第二天往往还要把失败路线重新走一遍。

一条负结果的价值，不在于它让文档更完整，而在于它让问题空间变小。

如果时间线没有留下，我不会事后按记忆补精确分钟。最多记录“先后关系可确认，具体时间缺失”。诚实的粗粒度，比虚构的精确更可靠。

我给截图文件也加了同样的约束。文件名至少包含日期、构建和状态，旁边放一份很短的说明：截图前做了什么，截图后是否继续操作，画面能支持什么，不能支持什么。这样一张图离开聊天窗口后，仍然有上下文。

单看图片哈希只能证明文件没有被悄悄替换，不能证明拍摄时的设备与构建。单看构建号也不能证明截图来自那次安装。哈希、版本和操作记录要互相咬住，缺一个就把可信范围缩小。

回退点要在改之前准备

调试最容易失控的时刻，不是报错出现，而是连续尝试开始。清缓存、换配置、改资源、升级依赖、重启工具一起做，最后问题消失了。你得到一个绿色结果，却失去了答案。

回退点能挡住这种冲动。它可以是一份工程副本、一个 commit、一份锁定的配置，也可以是已知可运行的归档。重点不是形式，而是你能准确回到上一状态。

没有回退点时，一次只改一个变量也不够，因为你无法确认自己真的回到了基线。

我给自己加了三条停止条件：现象不能稳定复现时停止；一次改动已经混入第二个变量时停止；没有可恢复基线时停止。停止不是放弃，它是在保护下一次实验的解释力。

我现在实际使用的五格记录

遇到新问题，我先写下面五格，再决定要不要打开代码：

五格调试记录

现象：只写看见了什么，不先写原因。 环境：设备、系统、构建、配置和复现入口。 单一变量：这次只改什么？它要排除哪条解释？ 证据：日志、截图、配置差异或构建产物。 回退点：如何恢复到本轮之前？ 

然后再补两行：停止条件是什么，当前还有哪些未知。

这份记录不会自动找到答案。它只会阻止我在证据还没到位时，把一个暂时恢复正常的画面写成根因关闭。对自己的小项目来说，它至少把下一步收窄成了可以验证的动作。

如果要把问题交给另一个人，我还会附上一个最小交接包：复现入口、最近一次可用构建、当前异常截图、这轮唯一改动、验证结果和未解释项。文件不必多，顺序必须清楚。

以这次 fallback 为例，交接包会写：进入设置页查看 AI engine；当前截图显示回退路径；设备与系统细节待补；下一步只查能力条件和配置；在这之前不要改业务逻辑。以图标问题为例，则写：源资产、最终配置和 build 9 归档产物已保留；缺修复前真机图与系统桌面验收；不要宣称透明设置已经构成唯一根因。

这两份交接说明都没有“已解决”。一个停在路径识别，一个停在构建产物。进度不是用绿色或红色表示，而是用证据已经走到哪一层表示。

下一轮怎样把缺口补齐

下一次复测 fallback，我会先记录设备型号、系统版本、相关能力开关、App 构建号和进入页面的步骤。然后只改变一个条件，再看状态文案是否变化。若切换条件后仍然回退，这条负结果也要入档。

图标验收则从同一构建开始：保存源资产与配置哈希，完成归档，确认归档中的图标文件，再安装到真机，分别截取浅色与深色桌面。截图里要能对应构建，不混用旧安装。

这些动作不保证找到根因，却能把当前三处缺口补上：环境快照、前后对照、真机结果。补齐后，文章才有资格从“最终材料存在”前进到“这次改动在目标环境中通过”。

下面这张不是留给读者填写的空表。我把这次真实保留下来的现象、环境缺口、下一变量、证据、回退点和停止条件全部写进去了；最后一格也明确标成“根因尚未关闭”。

哪些结论这次不写

这次没有足够材料证明具体设备为什么无法使用目标框架；没有完整的图标修复前后链路；没有多台设备和多个系统版本的重复测试；也没有系统桌面的全尺寸验收。

因此，这篇不是某个框架的兼容指南，也不是一份图标配置的通用答案。它只展示两个真实、但不完整的 iOS 记录，以及我怎样让结论停在证据能够到达的位置。

调试不是把故事讲圆。调试是知道哪一句可以落笔，哪一句还要等下一次复现。

如果你手上也有一个反复出现的问题，先别继续试第十一个办法。把现象、环境、单一变量、证据、回退点写满，再看缺的是哪一格。