# TH1 重要变更记录

本文档记录会影响工程打包、启动、资源加载、热更新、序列化兼容或跨平台行为的重要工程变更。普通业务功能变更仍以代码提交和对应子系统文档为准。

## 2026-06-11 HybridCLR / YooAsset 出包链排查与修正

### 背景

在 TH1 Build Panel 执行 `准备当前平台出包（热更 DLL + AOT + AB）` 时，Unity Console 出现：

```text
Assertion failed on expression: 'm_InstanceIDToAssetBundleIndex.count(id) > 0'
UnityEditor.BuildPipeline:BuildAssetBundles(...)
YooAsset.Editor.TaskBuilding_BBP:Run(...)
TH1YooAssetBuildTools:BuildBuiltinDefaultPackage(...)
```

面板同时显示 AOT Metadata 缺少：

```text
mscorlib.dll.bytes
System.dll.bytes
System.Core.dll.bytes
MemoryPack.dll.bytes
System.Runtime.CompilerServices.Unsafe.dll.bytes
```

### 根因

首要根因是本机尚未执行 HybridCLR Installer。`HybridCLR/Generate/All` 实际失败，日志中有：

```text
You have not initialized HybridCLR, please install it via menu 'HybridCLR/Installer'
```

由于旧工具通过 `EditorApplication.ExecuteMenuItem("HybridCLR/Generate/All")` 间接触发，失败没有可靠传回 TH1 Build Panel，后续仍继续执行热更 DLL 拷贝和 YooAsset AB 构建，导致面板误显示 `Prepare Player Build OK`，但 `StreamingAssets/HybridCLR/AOTAssemblies` 仍缺少必要 AOT metadata。

### 已做工程修正

- `Unity/Assets/Scripts/TH1_Logic/Editor/HybridCLR/TH1HybridCLRBuildTools.cs`
  - `GenerateAll()` 改为显式检查 HybridCLR 是否已安装。
  - 直接调用 `HybridCLR.Editor.Commands.PrebuildCommand.GenerateAll()`，失败时抛出 `BuildFailedException`。
  - Generate All 后校验 `HybridCLRData/AssembliesPostIl2CppStrip/<BuildTarget>` 是否存在，并检查项目要求的 AOT metadata 源 DLL 是否齐全。
  - `BuildAndCopyHotfixArtifacts()` 只有在热更 DLL 和 AOT metadata 都复制成功时才返回成功。

- `Unity/Assets/Scripts/TH1_Logic/Editor/YooAsset/TH1YooAssetBuildTools.cs`
  - YooAsset `DefaultPackage` 构建从 BBP (`BuildPipeline.BuildAssetBundles`) 切到 SBP (`ScriptableBuildPipeline`)。
  - 原因：Unity 2022 + YooAsset 2.1.1 下，YooAsset BBP 任务会进入 Unity 老接口 `BuildPipeline.BuildAssetBundles`；YooAsset 自身也在 Unity 2021+ 对 BBP 给出推荐使用 SBP 的警告。
  - SBP 不支持 `ForceRebuild`，因此构建模式使用 `IncrementalBuild`，同时保留 `BuildinFileCopyOption = ClearAndCopyAll`，保证 `StreamingAssets/Bundles/<PackageName>` 会清理并重拷本次内置包。

### 操作要求

首次配置或换机后，必须先执行：

```text
Tools/TH1/iOS Migration/HybridCLR/1. Run HybridCLR Installer
```

在 HybridCLR Installer 窗口中点击 `Install`，完成后再执行 TH1 Build Panel 的一键准备/出包流程。

成功状态应满足：

- `TH1.Hotfix.dll.bytes` 已生成并复制到 `Assets/StreamingAssets/HybridCLR/HotfixDlls`。
- AOT Metadata 面板状态为 OK。
- `Assets/StreamingAssets/HybridCLR/AOTAssemblies` 下存在项目要求的 `.dll.bytes`。
- YooAsset `DefaultPackage` 构建成功并复制到 `Assets/StreamingAssets/Bundles/DefaultPackage`。

### SBP 风险与规则

- SBP 不是修复 HybridCLR Installer 缺失的必要条件；HybridCLR 缺失应由 HybridCLR 工具链检查解决。
- SBP 是当前 Unity 2022 + YooAsset 2.1.1 更推荐的 AB 构建路径，可规避 BBP 进入 `BuildPipeline.BuildAssetBundles` 后触发的 Unity 内部断言。
- 从 BBP 切到 SBP 后，AB 二进制、依赖收集细节和 hash 不保证与旧 BBP 产物完全一致。
- 如果已有线上远程热更包使用 BBP 生成，不要把 BBP 与 SBP 产物混合作为同一条差分热更链。应从一个完整新包版本开始验证和发布。
- 切 SBP 后至少做资源烟测：主菜单、配置读取、UI 打开、进一局游戏、地图/单位/音效加载。

### 后续排查入口

如果再次出现同类出包问题，优先检查：

1. Unity Console / Editor.log 是否有 HybridCLR Installer 或 Generate All 失败。
2. `HybridCLRData/AssembliesPostIl2CppStrip/<BuildTarget>` 是否存在。
3. `Assets/StreamingAssets/HybridCLR/AOTAssemblies` 是否包含全部要求的 `.dll.bytes`。
4. YooAsset 构建日志中的 pipeline 是 `SBP` 还是 `BBP`。
5. 如必须回退 BBP，若 `m_InstanceIDToAssetBundleIndex.count(id) > 0` 断言复现，应重新切回 SBP 并按新完整包版本验证。