什么是 Addressables

1
2

var prefab = Resources.Load<GameObject>("Prefabs/Player");
Instantiate(prefab);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

          ┌─────────────────────────────────────────┐
          │           你的游戏代码                    │
          │   Addressables.LoadAssetAsync<T>("地址")  │
          └───────────────────┬─────────────────────┘
                              │
          ┌───────────────────▼─────────────────────┐
          │           Addressables 系统              │
          │  · 地址解析   · 依赖分析   · 引用计数      │
          │  · 分组打包   · 远程下载   · 目录管理      │
          └───────────────────┬─────────────────────┘
                              │
          ┌───────────────────▼─────────────────────┐
          │              AssetBundle                │
          └─────────────────────────────────────────┘

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

Address "Player"
      │ 属于
      ▼
   Asset Entry ──标记──> Label "character"
      │ 归属
      ▼
    Group "Characters" ──打包──> Bundle (.bundle)
      │ 记录在
      ▼
   Catalog (catalog.json)
      │ 存放位置由
      ▼
   Profile 变量（本地 / 远程）

1
2
3
4
5

{
  "dependencies": {
    "com.unity.addressables": "1.21.21"
  }
}

1
2
3
4
5

Assets/AddressableAssetsData/
├── AddressableAssetSettings.asset   # 系统总配置
├── AssetGroups/                     # 默认资源组
├── DataBuilders/                    # 打包脚本
└── ...

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

public class LoadExample : MonoBehaviour
{
    async void Start()
    {
        // 异步加载（推荐）：await 等待完成，拿到资源
        AsyncOperationHandle<GameObject> handle =
            Addressables.LoadAssetAsync<GameObject>("Player");

        await handle.Task;

        if (handle.Status == AsyncOperationStatus.Succeeded)
        {
            GameObject prefab = handle.Result;
            Instantiate(prefab);
        }

        // 用完释放（重要！）
        Addressables.Release(handle);
    }
}

1
2
3
4
5
6

var handle = Addressables.LoadAssetAsync<GameObject>("Player");
handle.Completed += op =>
{
    if (op.Status == AsyncOperationStatus.Succeeded)
        Instantiate(op.Result);
};

1
2
3
4
5
6
7
8
9

AsyncOperationHandle<GameObject> handle =
    Addressables.InstantiateAsync("Player", parent: transform);

await handle.Task;

GameObject go = handle.Result;

// 销毁实例并释放引用
Addressables.ReleaseInstance(go);

1
2
3
4
5
6
7
8
9

// 加载 Sprite
var spriteHandle = Addressables.LoadAssetAsync<Sprite>("Icon_Coin");
await spriteHandle.Task;
image.sprite = spriteHandle.Result;

// 加载 TextAsset（配置文本）
var textHandle = Addressables.LoadAssetAsync<TextAsset>("config_level");
await textHandle.Task;
string json = textHandle.Result.text;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

var handle = Addressables.LoadAssetAsync<GameObject>("Player");

// 1. 检查状态
handle.Status;              // None / Succeeded / Failed
handle.IsValid();           // 句柄是否有效
handle.IsDone;              // 是否完成

// 2. 获取进度
handle.PercentComplete;     // 0.0 ~ 1.0

// 3. 取结果
handle.Result;

// 4. 注册回调（可注册多个）
handle.Completed += OnLoaded;

// 5. 同步等待（阻塞当前线程，谨慎使用！）
handle.WaitForCompletion();

// 6. 释放
Addressables.Release(handle);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

// 方式一：多个地址一次加载
var keys = new List<string> { "Icon_Coin", "Icon_Gem", "Icon_Heart" };
var handle = Addressables.LoadAssetsAsync<Sprite>(keys, null, MergeMode.Union);
await handle.Task;
foreach (var sprite in handle.Result) { /* ... */ }
Addressables.Release(handle);

// 方式二：按标签批量加载
var labelHandle = Addressables.LoadAssetsAsync<Sprite>("ui_icon", null);
await labelHandle.Task;
Addressables.Release(labelHandle);

1
2
3
4
5
6
7

var h1 = Addressables.LoadAssetAsync<GameObject>("Player");  // 计数 = 1
var h2 = Addressables.LoadAssetAsync<GameObject>("Player");  // 计数 = 2

Addressables.Release(h1);   // 计数 = 1，资源仍在内存
Addressables.Release(h2);   // 计数 = 0，资源被卸载

// 如果忘记 Release，资源会一直留在内存中 —— 内存泄漏！

1
2
3
4
5
6

var go = await Addressables.InstantiateAsync("Enemy").Task;
// 用 ReleaseInstance 销毁实例并释放
Addressables.ReleaseInstance(go);

// 如果第二个参数 trackHandle 传 false，则 InstantiateAsync 不跟踪句柄，
// 此时用普通的 Destroy(go) 即可，但要自己确保资源加载句柄被释放

1
2
3
4

Local.BuildPath  = [UnityEngine.AddressableAssets.Addressables.BuildPath]/[BuildTarget]
Local.LoadPath   = {UnityEngine.AddressableAssets.Addressables.RuntimePath}/[BuildTarget]
Remote.BuildPath = ServerData/[BuildTarget]
Remote.LoadPath  = http://localhost/[BuildTarget]

1
2
3
4
5

ServerData/StandaloneWindows64/
├── catalog.json                    # 目录清单
├── catalog_xxx.hash                # 目录哈希
├── catalog_xxx.bundle
└── *.bundle                        # 资源包

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

async void CheckUpdate()
{
    // 1. 检查 Catalog 是否有更新
    AsyncOperationHandle<List<string>> checkHandle =
        Addressables.CheckForCatalogUpdates();
    await checkHandle.Task;
    List<string> catalogs = checkHandle.Result;

    if (catalogs != null && catalogs.Count > 0)
    {
        // 2. 更新本地 Catalog
        AsyncOperationHandle<List<IResourceLocator>> updateHandle =
            Addressables.UpdateCatalogs(catalogs);
        await updateHandle.Task;
    }

    // 3. 查询某个资源需要下载多少字节
    long size = await Addressables.GetDownloadSizeAsync("Chapter_02").Task;
    Debug.Log($"需要下载 {size / 1024f / 1024f:F2} MB");

    if (size > 0)
    {
        // 4. 下载依赖
        var downloadHandle =
            Addressables.DownloadDependenciesAsync("Chapter_02");
        while (!downloadHandle.IsDone)
        {
            Debug.Log($"下载进度：{downloadHandle.PercentComplete:P0}");
            await System.Threading.Tasks.Task.Yield();
        }
        Addressables.Release(downloadHandle);
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

using UnityEngine;
using UnityEngine.AddressableAssets;

public class Spawner : MonoBehaviour
{
    // 在 Inspector 中通过 AssetReference 选择一个 Addressable 资源
    public AssetReferenceGameObject enemyRef;

    async void Spawn()
    {
        // 通过引用加载，而非硬引用
        AsyncOperationHandle<GameObject> handle = enemyRef.InstantiateAsync();
        await handle.Task;
        // ...
    }

    void OnDestroy()
    {
        enemyRef.ReleaseInstance(); // 释放该引用实例化的对象
    }
}

1
2
3
4
5

var handle = Addressables.LoadAssetsAsync<GameObject>("character", null);
await handle.Task;
foreach (var go in handle.Result)
    Instantiate(go);
Addressables.Release(handle);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using UnityEngine.SceneManagement;

// 加载场景（单场景模式，替换当前场景）
AsyncOperationHandle<SceneInstance> handle =
    Addressables.LoadSceneAsync("Level_01", LoadSceneMode.Single);
await handle.Task;

// 叠加加载（Additive）
var addHandle = Addressables.LoadSceneAsync("UI_HUD", LoadSceneMode.Additive);
await addHandle.Task;

// 卸载场景
await Addressables.UnloadSceneAsync(addHandle).Task;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

// 错误：加载后没有释放
void ShowIcon()
{
    Addressables.LoadAssetAsync<Sprite>("Icon").Completed += op =>
        img.sprite = op.Result;
}

// 正确：保存句柄，关闭界面时释放
AsyncOperationHandle<Sprite> _iconHandle;

async void ShowIcon()
{
    _iconHandle = Addressables.LoadAssetAsync<Sprite>("Icon");
    await _iconHandle.Task;
    img.sprite = _iconHandle.Result;
}

void OnDestroy()
{
    if (_iconHandle.IsValid())
        Addressables.Release(_iconHandle);
}

1
2
3
4
5

public static class Addresses
{
    public const string Player = "Player";
    public const string LoginUI = "UI/Login";
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

using System.Collections.Generic;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

public static class ResLoader
{
    // 记录句柄，统一在合适时机释放
    static readonly Dictionary<string, AsyncOperationHandle> _handles = new();

    public static async System.Threading.Tasks.Task<T> LoadAsync<T>(string address)
    {
        if (_handles.TryGetValue(address, out var cached) && cached.IsValid())
            return (T)cached.Result;

        var handle = Addressables.LoadAssetAsync<T>(address);
        await handle.Task;

        if (handle.Status == AsyncOperationStatus.Succeeded)
        {
            _handles[address] = handle;
            return handle.Result;
        }

        Debug.LogError($"加载失败：{address}");
        Addressables.Release(handle);
        return default;
    }

    public static void Release(string address)
    {
        if (_handles.TryGetValue(address, out var handle))
        {
            if (handle.IsValid()) Addressables.Release(handle);
            _handles.Remove(address);
        }
    }

    public static void ReleaseAll()
    {
        foreach (var kv in _handles)
            if (kv.Value.IsValid()) Addressables.Release(kv.Value);
        _handles.Clear();
    }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

1. 安装 Addressables 包
        │
2. Window > Asset Management > Addressables > Groups
        │
3. 创建分组：Local / Remote
        │
4. 拖入资源，设置语义化地址（如 "Player"）
        │
5. 配置 Play Mode Script = Use Asset Database（开发期）
        │
6. 代码加载：
     Addressables.InstantiateAsync("Player", parent);
        │
7. 用完 ReleaseInstance / Release
        │
8. 发布前 Build > New Build，切 Use Existing Build 验证
        │
9. 上传 ServerData 到 CDN，配置 Remote.LoadPath
        │
10. 运行时 CheckForCatalogUpdates → DownloadDependencies → 加载

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

public class AddressablesDemo : MonoBehaviour
{
    public string address = "Player";
    GameObject _instance;
    AsyncOperationHandle<GameObject> _handle;

    async void Start()
    {
        // 加载并实例化
        _handle = Addressables.InstantiateAsync(address, transform);
        await _handle.Task;

        if (_handle.Status == AsyncOperationStatus.Succeeded)
        {
            _instance = _handle.Result;
            Debug.Log("加载成功：" + address);
        }
        else
        {
            Debug.LogError($"加载失败：{address}，{_handle.OperationException}");
        }
    }

    void OnDestroy()
    {
        // 销毁实例并释放
        if (_instance != null)
            Addressables.ReleaseInstance(_instance);
    }
}