hz-unity-sdk-upgrade

Meta XR Unity SDK 升级

以证据为依据迁移项目。完成包解析和干净编译是检查点，并不能证明应用仍可正常运行。

以最短的已验证路径为目标。在时间有限的会话中，完成包和提供程序迁移，移除重复的 SDK 代码，迁移所有已知的生产者和消费者，并在进行可选清理或更广泛的平台验证之前获得干净编译。若已知的旧版消费者或供应商提供的 SDK 文件仍然存在，就不要把剩余时间花在打磨一个已通过编译的项目设置上。

对于 Unreal、原生 Android 或 Spatial SDK、WebXR 或 Immersive Web SDK（IWSDK）， 以及通用跨平台升级，请使用 hz-api-upgrade。

必需的工作流程

1. 阅读 Unity 升级操作手册。对 Unity 版本、渲染管线、XR 提供程序、Meta 软件包、供应商提供的 Assets/Oculus 内容、程序集定义以及受影响的场景/预制件进行范围有限的浅层盘点。记录路径和旧版符号，不要逐一读取大型序列化资源，也不要构建完整的 GUID 映射。创建一份清单，列出受影响的生产端、消费端、序列化资源、设置和测试；后续应更新这份清单，而不是重复盘点或启动重复的盘点子任务。
2. 根据软件包或 SDK 系列标记确定源 SDK 版本和目标 SDK 版本。将 Meta XR 软件包版本、通过托管 OVRPlugin API 报告的捆绑原生 OVRPlugin 版本、Unity 编辑器版本和 XR 提供程序视为相互独立的维度；不要根据其中一项推断另一项。如果任一 SDK 版本不明确，请报告证据并标注该值为推断值。
3. 选择替代项前，先使用 metavr 查询当前文档。先进行一次覆盖完整版本范围的查询，再针对每个当前启用且影响较大的维度各进行一次查询，然后获取最相关的权威结果。只有当软件包元数据或变更日志表明某个中间版本很重要时，才搜索单个已发布版本。确定了相关官方指南以及下一迁移阶段所需的确切目标 API 签名后，就实施该阶段；不要继续探查相邻 API。只有出现新错误或清单中仍有未解决项时，才重新搜索。
4. 将缺失或不相关的结果视为文档覆盖缺口。在升级报告中记录查询及结果；不要凭记忆填补缺口，也不要声称 metavr 找到了它未返回的指南。
5. 先更新软件包拓扑，再修改应用程序代码。移除重复的供应商 SDK 内容，使相关 Meta 软件包以及目标版本所需的任何桥接/适配器软件包保持兼容，并有意更新 XR 提供程序，解决程序集定义引用问题。验证软件包声明以及序列化的加载器/提供程序设置；安装 OpenXR 软件包并不会启用其加载器。在此阶段内运行并等待任何必需的项目设置工具完成，然后重新扫描供应商 SDK 代码，因为导入或设置自动化可能会重新创建文件。首次更改后的编译必须先于软件包源代码检查或场景和预制件的深入迁移；根据编译诊断决定接下来检查什么。
6. 在软件包/提供程序阶段之后，以及每个连贯的迁移阶段之后，运行下面的关键编译循环。不要在编译失败时继续叠加无关的迁移工作。
7. 将生产端和消费端一起迁移。在进行可选清理或平台检查之前，列出具体的消费端文件，并逐项标记为已迁移。搜索场景、预制件、序列化字段、自定义加载器、编辑器工具和测试，不要只搜索 .cs 调用点。不要为了获得干净的编译而删除或跳过受影响的消费端。
8. 如果项目使用 OVRSceneManager、OVRSceneRoom、OVRSceneAnchor 或自定义 Scene API 加载器，请在编辑前阅读 MRUK 迁移最佳实践，并在最终编译前运行其中的完成检查清单。
9. 将伴随的 Unity 主版本、XR 提供程序或 Input System 变更视为独立的迁移维度。按构建目标检查序列化的提供程序设置、必需的 OpenXR 功能组和交互配置文件、Active Input Handling、Unity.InputSystem 程序集引用、Android 入口点、权限、Addressables/Localization、渲染管线设置、色彩空间，以及适用时的 Android 最低 SDK。通过实时文档和已安装软件包 API 验证与版本相关的细节。
10. 分层验证：软件包解析、脚本编译、编辑/运行模式测试、Android 构建，然后在头显上验证权限、场景加载、输入、渲染和生命周期。对于编译，优先使用已安装且有文档记录的 Unity 编辑器控制 CLI 或桥接工具，在能够安全驱动项目已打开的 Editor 时使用它。否则，只有在确认同一项目未在其他位置打开后，才使用匹配的 Unity Editor 批处理模式。绝不要在同一项目上启动第二个 Editor，也不要终止无关的 Unity 进程。在升级报告中保留准确的命令和结果。
11. 只有在所要求的验证层全部通过，或已明确记录失败或未验证的层、阻塞层、证据以及具体的下一条命令后，才能结束。

关键执行与编译循环

将编译视为阻塞式反馈循环，而不是任务结束时的验证：

1. 编辑前，在环境支持的情况下进行一次全新的基线编译，并记录所有既有错误。
2. 完成 package 和 XR provider 检查清单，等待 package 解析和导入完成，然后立即编译。修复或回退所有新增的 package、assembly 和 API 错误，再迁移其他子系统。
3. 端到端迁移一个行为切片——对于 Scene API 迁移，包括生产者和所有已清点的使用方——然后再次编译。重新连接该切片的序列化资源和设置，然后再编译一次。
4. 失败时，检查第一个可操作的错误，核实已安装目标 API，或搜索该确切错误；进行最小且一致的修复，然后重新运行。编译报错时，不要开始无关工作。
5. 对于有时间限制的工作，预留大约最后三分之一的时间用于编译和修复循环，因为 Unity package 导入和域重载速度较慢。在此期间，每项操作都必须直接处理一个已知迁移事项：编辑、编译、检查当前的首个错误，或验证必需的生产者／使用方／package 不变量。不要开始新的清点、重复的子任务、大范围文档搜索、可选的项目级修复，或相邻 API 探索。不要启动最大运行时间超过剩余时间的命令。如果时间耗尽时编译仍报错，应报告编译失败和剩余错误，而不是声称已完成。
6. 最后一次代码、package 或序列化文件编辑之后，必须进行一次全新的干净编译；较早的干净结果不能验证之后的更改。
7. 如果编译以异步方式运行，应留在当前任务中，并轮询同一进程直至得到最终结果。不要安排提醒、推迟检查，或在验证仍待完成时返回。读取最新日志，并在继续之前修复当前错误；如果环境无法让进程保持连接，应报告编译尚未验证，而不是声称已完成。

关键完成关卡

报告完成之前：

• 核实确切的 package 集合，包括项目仍在使用的 API 所需的桥接／适配 package；例如，结合使用 Interaction SDK 和 OVR API 的项目可能需要 com.meta.xr.sdk.interaction.ovr。确认预期的 XR provider 已安装并启用，已移除或取消配置其旧版替代项，并且重复 vendored SDK 代码已清除。
• 重新扫描游戏代码、assembly definition、场景、prefab 和项目设置，检查所有受影响的旧版生产者和使用方。
• 保留受影响的使用方脚本及其 .meta GUID，并在原处迁移。除非请求范围明确要求保留，否则仍能编译的弃用使用方也表示迁移未完成；不要仅因某个使用方看似未使用就将其删除，而不检查代码和序列化引用。
• 如果 Scene API 已迁移至 MRUK，请确认加载器读取 AnchorLabels、处理 PlaneRect 和 VolumeBounds，并在运行时创建 MRUK 时初始化 SceneSettings。如果自定义加载器将分类映射到 prefab，请确认它会在任何共享的 null-prefab 防护之前选择全局网格表示，并将 GlobalMesh 路由到应用程序的渲染或碰撞组件。确认所有使用方（包括调试／导出器代码）都使用已迁移的约定。
• 确认序列化的 prefab 映射和 MRUK／provider 设置已重新连接；C# 编译无法证明这一点。
• 在报告中区分 package 解析、脚本编译、player 构建、Horizon Link 测试和独立设备测试。绝不能把较早阶段的验证结果当作较后阶段的证据。

文档命令

保留搜索结果时，请使用 JSON 输出：

metavr docs search --category UNITY --format json "Meta XR Unity SDK release notes <source> <target>"
metavr docs search --category UNITY --format json "<deprecated symbol> migration"
metavr docs search --category UNITY --format json "<package name> <compiler or runtime error>"
metavr docs fetch --format json "<URL returned by search>"

metavr docs search 是语义搜索，而非完整的版本间差异对比。版本查询结果较弱时，应按程序包和符号扩大搜索范围，而不是凭空编造破坏性变更清单。

如果无法使用 metavr，请勿编造搜索结果。请使用当前官方 Developer Center 页面以及已安装目标程序包的变更日志、公共 API 和示例，并说明未运行实时 CLI 检索。

防护措施

• 将捆绑或缓存的破坏性变更摘要视为线索，而非权威依据；请根据当前官方文档和已安装的目标程序包进行核实。
• 默认不要建议逐步升级。应根据程序包约束和证据选择直接迁移或分阶段迁移。
• 在确认项目资源的使用方之前，不要删除项目资源、重新生成序列化文件或整体更改场景。
• 不要将已弃用等同于已移除。请根据目标版本的支持情况和请求范围决定是否立即迁移。
• 不要仅凭编译成功就报告成功。Unity 序列化、Android 权限和仅限设备的路径仍可能失败。

参考资料

• Unity 升级操作手册
• Scene API 到 MRUK 迁移最佳实践