TH1 重要变更记录

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

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

背景

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

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

面板同时显示 AOT Metadata 缺少：

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

根因

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

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> 会清理并重拷本次内置包。

操作要求

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

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 打开、进一局游戏、地图/单位/音效加载。

后续排查入口

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

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

4.4 KiB Raw Blame History Unescape Escape