Unity 游戏启动卡死：AI 用「最小集 + 增量」对照实验定位并修复了一个 Harmony 兼容 bug

Unity 游戏启动卡死：AI 用"最小集 + 增量"对照实验锁定并修复了一个 Harmony 兼容 bug

摘要：游戏启动后主菜单无限刷空引用异常（NRE）进不去，几百 KB 的日志里全是堆栈。我和 AI 用"三分对照实验"——先干净环境、再一步步加——把问题收敛到 Harmony 与 HugsLib 的版本不兼容，降级 Harmony 一个 patch 版本后 89 个 mod 全部正常进主菜单。本文还原这个排障思路，它适用于绝大多数"费解崩溃"。

背景

给非 Steam 版游戏加装 mod 合集时，改好 ModsConfig.xml、启动——结果一进加载就卡死，主菜单根本进不去。打开日志，几万行全是一样的空引用（NullReferenceException）堆栈，无限刷屏。这类"日志刷屏但看不出哪行是关键"的崩溃，最坑人：让你以为信息量很大，其实毫无头绪。

正文

第一步：别看堆栈，先建立"可控基线"

面对几万行同类日志，第一反应别去逐行读——那是大海捞针。正确做法是先制造一个能稳定复现、又足够简单的环境：

1. 先把 mod 全关掉，用一个几乎空的环境启动游戏。
2. 确认"干净版"能正常进主菜单。
3. 从这个干净状态出发，一次只加一点点，每步都验证。

这保证了每一步的变量可控：崩溃不是玄学，而是某一次"增量"引入的。

第二步：用反编译定位"公共罪魁"

干净的 mod 分层全部正常，但全量加载就刷 NRE。AI 建议不要继续盲猜，而是反编译相关 DLL看堆栈真正指向的库。日志里反复出现的框，往往是某一个被大量三方的 HarmonyPatch（补丁）共同依赖的基础库。

反编译后锁定了两个高频嫌疑：Harmony 与 HugsLib——前者是所有 mod 的打补丁框架，后者是它们共享的依赖库。

第三步：做"最小集 + 增量"的对照实验

这是最硬核也最关键的一步。思路是：

• 维护一个"最小编译验证集"：只开 Harmony + HugsLib + 一个被测 mod。
• 在"含 Harmony 新版本 / 不含"两种配置下反复切换，观察 NRE 是否消失。
• 逐 mod 增量加入，找出那个"加入后就崩"的最小组合。

结果：问题被锁定在 Harmony 2.3.3.0 与 HugsLib（及被其驱动的组合）不兼容。当把 Harmony 从 2.3.3.0 降级到 2.2.2.0 后：

• NRE 刷屏消失；
• 89 个 mod 全部显示为绿色（兼容）；
• 成功进入主菜单。

一个 patch 版本的差异，从"进不去"到"全绿"，反差极大。

第四步：处理后续"连锁"问题

升级战斗还没结束。降级 Harmony 解决了主问题，接着又暴露了：

• 启动变慢（首次读取大量 mod 的预期代价）；
• RocketMan 的缓存连锁卡死（某个 mod 的缓存逻辑一旦触发就卡住，需要清缓存或调整加载顺序）；
• 个别 mod 缺文件（下载不完整）。

这些都是同一套"最小集 + 增量"方法论逐个击破的：每次只引入一个变量，确认是它再处理。

踩坑记录

• 日志刷屏≠容易排障：几万行同类堆栈反而说明"日志本身帮不上忙"，别舍不得关掉日志驱动的直觉。
• 基础库的 patch 版本差异极大：Harmony 这种三方共依赖的打补丁框架，升一个 minor 就可能和 HugsLib 等组合崩掉。升级依赖前先查兼容矩阵。
• 不要一上来就全量开关：先"干净版 + 一点点加"，比"全关再全开"更容易定位。
• 改一点验证一次：每个增量改动都要能复现，才能把"玄学崩溃"变成"可控复现"。

总结

这次排障的核心方法论就一句话：面对费解崩溃，先回到最小可控环境，再逐步增量回归，每一个增量都用对照验证。 它把"几万行 NRE 刷屏"这种看起来无从下手的场景，收敛成"一次依赖降级"就能解决的具体修复。

下一步可以做得更稳：把"mod 兼容矩阵（Harmony/HugsLib 版本 → 各 mod 状态）"固化成一张表，下次升级依赖前先按表预检，而不是再踩一遍。