unity-addressables-design

**调用此模块中的任何技能之前：**如果你准备根据技能的名称或描述猜测参数并调用技能，请先停下——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已经从 recommend/schema 中获得参数定义，则可以直接进行 dryRun。

触发条件

• 编写或审查 Addressables 代码
• 异步加载资源/场景
• 热更新或目录刷新
• 版本迁移
• 编写或审查 Addressables 代码、异步加载资源/场景、配置热更新或目录刷新、版本迁移

Addressables - 设计规则

参考模块。每条规则均根据两个版本的 Unity Addressables 源码提炼而成：

• 1.22.3 — [email protected]（Unity 2022，最低版本 2019.4）
• 2.9.1 — com.unity.addressables@8460f1c9c927（Unity 6，最低版本 2023.1）

每条规则都引用了具体的文件/行号，确保推理过程可审计，AI 不会依据过时记忆随意发挥。

模式：仅供文档参考——无需限制 REST 技能；在任何运行模式（Approval / Auto / Bypass）下均可自由加载。

何时加载此模块

在编写或审查以下内容之前加载：

• Addressables.InitializeAsync() / LoadContentCatalogAsync() 引导代码
• LoadAssetAsync<T> / LoadAssetsAsync<T> / InstantiateAsync 及其句柄释放
• LoadSceneAsync / UnloadSceneAsync——尤其是使用 SceneReleaseMode 时（2.9.1）
• CheckForCatalogUpdates → UpdateCatalogs → CleanBundleCache 补丁流程
• GetDownloadSizeAsync / DownloadDependenciesAsync / ClearDependencyCacheAsync
• AssetReference / AssetReferenceT<T> 字段声明与加载/释放
• 任何直接调用 WaitForCompletion() 或使用 AsyncOperationHandle 的代码
• 从 1.22.3 迁移到 2.9.1——已移除的 API、签名已变更的重载

版本差异矩阵

区域	1.22.3 (Unity 2022)	2.9.1 (Unity 6)
非异步变体（LoadAsset、Instantiate、LoadScene 等）	[Obsolete] — 编译警告	已移除 — 编译错误
IList<object> 多键重载	存在	已替换为 IEnumerable
SceneReleaseMode 枚举	不存在	新增 — 控制场景卸载时的资源包生命周期
LoadSceneAsync 的 releaseMode 参数	不存在	默认值为 SceneReleaseMode.ReleaseSceneWhenSceneUnloaded
LoadAssetsAsync<T>(string key, ...)	不存在	新增字符串键重载
UpdateCatalogs(bool autoCleanBundleCache, ...)	不存在	新增重载
LegacyResourcesLocator / LegacyResourcesProvider	存在	已移除
DiagnosticEvent / DiagnosticEventCollector	存在	已移除
ResourceManagerEventCollector	存在	已移除
ResourceManager.RegisterDiagnosticCallback()	[Obsolete]	已移除
InitializationOperation 属性	[Obsolete]，返回 default	已移除
BinaryCatalogInitializationData	不存在	新增
CachedFileProvider	不存在	新增

关键规则摘要

#	规则	版本	源锚点
1	所有非 Async 变体（LoadAsset、Instantiate、LoadScene、UnloadScene、GetDownloadSize、DownloadDependencies、Initialize、LoadContentCatalog）在 1.22.3 中均为 [Obsolete]，并在 2.9.1 中移除。始终使用 *Async 形式。	Both	Addressables.cs:1.22.3:862-2226、Addressables.cs:2.9.1（不存在）
2	Load/Instantiate 调用返回的每个 AsyncOperationHandle 都必须通过 Addressables.Release(handle) 释放。忘记释放会导致 AssetBundle 永久滞留在内存中，即使场景已卸载也不例外。	Both	AsyncOperationHandle.cs:2.9.1:178-203
3	WaitForCompletion() 会同步阻塞调用线程。在 WebGL 上不受支持，并会抛出异常。切勿在生产环境的主线程上调用；请改用 await handle.Task 或 Completed 事件。	Both	AsyncOperationHandle.cs:2.9.1:178-203
4	2.9.1 中的 LoadSceneAsync 新增了 SceneReleaseMode releaseMode（默认值为 ReleaseSceneWhenSceneUnloaded）。如果 Single 模式的加载会卸载你的附加场景，而你需要让 AssetBundle 保持有效，请传入 OnlyReleaseSceneOnHandleRelease 并手动释放句柄。	2.9.1	ISceneProvider.cs:2.9.1:14-26、Addressables.cs:2.9.1:1914
5	2.9.1 中，多键重载的参数类型从 IList<object> 改为 IEnumerable。旧的 IList<object> 重载已不存在，请传入 IEnumerable 或 string[]。	2.9.1	Addressables.cs:2.9.1:1148,1566,1636
6	LegacyResourcesLocator 和 LegacyResourcesProvider 已在 2.9.1 中移除。针对 Unity 6 的代码中不要引用它们。	2.9.1	Runtime/ResourceLocators/（在 2.9.1 中不存在）
7	ResourceManager.RegisterDiagnosticCallback() 在 1.22.3 中为 [Obsolete]，并在 2.9.1 中移除。请改用 Addressables Profiler 窗口。	2.9.1	ResourceManager.cs:1.22.3:353（在 2.9.1 中不存在）
8	目录更新流程必须严格按顺序执行：CheckForCatalogUpdates → UpdateCatalogs。在 2.9.1 中，UpdateCatalogs(bool autoCleanBundleCache, ...) 可在一次调用中自动清理过期的 AssetBundle。	Both	Addressables.cs:2.9.1:2092-2147
9	AssetReference.LoadAssetAsync<T>() 返回的句柄必须通过 assetRef.ReleaseAsset() 释放，不能使用 Addressables.Release(handle)。混用两种方式会导致重复释放异常。	Both	AssetReference.cs:1.22.3:44-46
10	InitializationOperation 属性（1.22.3）为 [Obsolete]，且返回 default。不要等待它；请改用 await Addressables.InitializeAsync()。	1.22.3	Addressables.cs:1.22.3:981-982

子文档导航

子文档	阅读时机
INIT.md	InitializeAsync / LoadContentCatalogAsync / 目录加载顺序 / autoReleaseHandle 语义
HANDLES.md	AsyncOperationHandle<T> 生命周期——Completed、WaitForCompletion、Release、IsDone、Status、OperationException、引用计数
LOADING.md	LoadAssetAsync、LoadAssetsAsync（所有重载及版本差异）、MergeMode、InstantiateAsync、ReleaseInstance
SCENE.md	LoadSceneAsync / UnloadSceneAsync / SceneInstance.ActivateAsync / SceneReleaseMode（2.9.1）/ activateOnLoad=false 模式
UPDATE.md	CheckForCatalogUpdates → UpdateCatalogs 流程 / autoCleanBundleCache（2.9.1）/ CleanBundleCache / ResourceLocatorInfo
DOWNLOAD.md	GetDownloadSizeAsync / DownloadDependenciesAsync / ClearDependencyCacheAsync / DownloadStatus 结构体
ASSETREF.md	AssetReference / AssetReferenceT<T> / LoadAssetAsync / ReleaseAsset / OperationHandle 属性 / IsDone 检查
PITFALLS.md	30 个带版本标记的具体幻觉陷阱，以及旧版 API 迁移章节

路由到其他模块

• 面向 Addressables 使用者的 Asmdef 布局 → 加载 asmdef
• 跨多个 Addressables 操作的异步编排 → 加载 async
• 架构层面的决策（Addressables 与 YooAsset 的比较、组策略）→ 加载 architecture
• 对加载/释放热点路径进行性能审查 → 加载 performance

版本范围

本文档适用于两个版本：

• 1.22.3 — 随 Unity 2022 LTS 发布。包含仍供迁移使用的 [Obsolete] 非 Async 变体。
• 2.9.1 — 随 Unity 6 (2023.1+) 发布。所有 [Obsolete] API 均已移除。新增 SceneReleaseMode、二进制目录格式和 AutoGroupGenerator。

某条规则仅适用于一个版本时，会标记为 [1.22.3] 或 [2.9.1]。未标记的规则适用于两个版本。

迁移说明（防幻觉屏障）

旧版 API	状态	替代项	来源
Addressables.Initialize()	在 1.22.3 中为 [Obsolete]，在 2.9.1 中已移除	Addressables.InitializeAsync()	Addressables.cs:1.22.3:862-864
Addressables.LoadAsset<T>(key)	在 1.22.3 中为 [Obsolete]，在 2.9.1 中已移除	Addressables.LoadAssetAsync<T>(key)	Addressables.cs:1.22.3:992-1007
Addressables.LoadAssets<T>(keys, cb, mode)	在 1.22.3 中为 [Obsolete]，在 2.9.1 中已移除	Addressables.LoadAssetsAsync<T>(keys, cb, mode)	Addressables.cs:1.22.3:1242-1276
Addressables.Instantiate(key, ...)	在 1.22.3 中为 [Obsolete]，在 2.9.1 中已移除	Addressables.InstantiateAsync(key, ...)	Addressables.cs:1.22.3:1892-1972
Addressables.LoadScene(key, ...)	在 1.22.3 中为 [Obsolete]，在 2.9.1 中已移除	Addressables.LoadSceneAsync(key, ...)	Addressables.cs:1.22.3:2090-2106
Addressables.UnloadScene(handle, ...)	在 1.22.3 中为 [Obsolete]，在 2.9.1 中已移除	Addressables.UnloadSceneAsync(handle, ...)	Addressables.cs:1.22.3:2180-2226
Addressables.GetDownloadSize(key)	在 1.22.3 中为 [Obsolete]，在 2.9.1 中已移除	Addressables.GetDownloadSizeAsync(key)	Addressables.cs:1.22.3:1547
Addressables.DownloadDependencies(key)	在 1.22.3 中为 [Obsolete]，在 2.9.1 中已移除	Addressables.DownloadDependenciesAsync(key)	Addressables.cs:1.22.3:1608
Addressables.InitializationOperation	在 1.22.3 中为 [Obsolete]，在 2.9.1 中已移除	await Addressables.InitializeAsync()	Addressables.cs:1.22.3:981-982
LoadResourceLocationsAsync(IList<object> keys, ...)	在 1.22.3 中存在，在 2.9.1 中已移除	LoadResourceLocationsAsync(IEnumerable keys, ...)	Addressables.cs:2.9.1:1148
GetDownloadSizeAsync(IList<object> keys)	在 1.22.3 中存在，在 2.9.1 中已移除	GetDownloadSizeAsync(IEnumerable keys)	Addressables.cs:2.9.1:1566
DownloadDependenciesAsync(IList<object> keys, mode, ...)	在 1.22.3 中存在，在 2.9.1 中已移除	DownloadDependenciesAsync(IEnumerable keys, mode, ...)	Addressables.cs:2.9.1:1636
LegacyResourcesLocator / LegacyResourcesProvider	在 1.22.3 中存在，在 2.9.1 中已移除	所有资源均使用 Addressables 组	Runtime/ResourceLocators/LegacyResourcesLocator.cs:1.22.3
ResourceManager.RegisterDiagnosticCallback(...)	在 1.22.3 中为 [Obsolete]，在 2.9.1 中已移除	Addressables Profiler 窗口	ResourceManager.cs:1.22.3:353
DiagnosticEvent / DiagnosticEventCollector	在 1.22.3 中存在，在 2.9.1 中已移除	Addressables Profiler / 自定义 IProfilerEmitter	Runtime/ResourceManager/Diagnostics/:1.22.3

如有疑问，请查阅引用的源代码，而不是依赖记忆。