Unity Addressables 使用说明（七）诊断工具（Diagnostic tools）

Addressables 包含诊断工具，用于分析你的 Addressables setup、performance 和 build result 。

Addressables Profiler Module

Addressables Profiler 是一个 Unity 编辑器 Profiler 模块，可以用来了解从 Addressables 加载的内容。

前提条件

1. 必须启用构建报告（Build Reports），并且需要运行时的构建报告。要启用构建报告，请转到Editor preferences，选择 Addressables preferences ，然后启用Debug Build Layout。
2. 收集运行内容的信息需要调试构建布局的构建时数据收集信息。这些文件存储在 <Project Directory>/Library/com.unity.addressables/buildReports 文件夹中。每次构建都会在该目录中创建一个新的构建报告文件。运行 Profiler 时，任何来自 Profiler 目标的 Profiler 数据将同步，并在 buildReports 文件夹中查找该运行时的构建报告文件。如果构建报告不存在（例如项目是在不同机器上构建的），Profiler 将不会显示该数据的信息。选择“在文件系统中查找”可以打开文件选择窗口，你可以使用它在磁盘的其他位置定位构建报告文件。
3. Profiler 运行需要 Unity Profiling Core API 包。要安装此包，可以通过包管理器或在启用Debug Build Layout时通过 Addressables 偏好设置窗口进行安装。
4. Profiler 模块不支持Play Mode Scripts Use Asset Database (Fastest)。内容必须构建并使用Use Existing Build based Play Mode Scripts”。

打开 Profiler 模块

要打开 Addressables Profiler ：

1. 打开 Profiler 窗口（Window > Analysis > Profiler）。
2. 在 Profiler 窗口的右上角，选择名为Profiler Modules的下拉按钮。
3. 启用名为Addressable Assets的选项。

查看模块

模块视图（module view）可用于观察在某一帧中加载了多少 AssetBundles、Assets、Scenes 和 Catalog 。

下图显示了一个目录中的三个资源和一个场景，以及六个 AssetBundles：

选择某一帧时，详细窗格（detail pane）会填充该帧的信息，并显示加载内容的树视图。

要更改显示的内容，请选择详细窗格工具栏中的下拉按钮View。

它有以下选项：

• Groups：在树视图中包含组。
• Asset Bundles：在树视图中包含 AssetBundles。
• Assets：在树视图中包含资源。
• Objects：在树视图中包含资源内加载的对象。
• Assets not loaded：显示在加载的 bundle 中但未主动加载的资源。

详细窗格有两个区域。左侧是内容的树视图，显示加载的内容，可以展开以显示详细内容。右侧是详细信息检查器，显示从树视图中选择的内容的详细信息。

Content Tree View

你可以根据个人喜好启用或禁用树视图列。在树视图标题上右键单击以显示可用列的列表。

每列根据行中的内容显示信息：

列名	描述
Name	根据类型，显示以下内容：组名、AssetBundle 文件名、资源地址或资源路径（如果未使用地址）、对象名或场景的资源类型。
Type	资源或对象的类型。
Handles	主动持有内容的 Addressables 句柄数量，通常称为引用计数。加载期间有一个附加句柄到内容。
Status	内容在该时间的状态，可以是：Queued（排队中）、Downloading（下载中）、Loading（加载中）、Active（活动）、Released（释放）。
%	如果Status为Downloading或Loading，则显示下载或加载操作的百分比进度。
Source	显示 AssetBundle 的加载来源：Local（本地）、Cache（缓存）、Download（下载）。
Refs By	引用该内容的元素数量。
Refs To	该内容引用的元素数量。

释放的资源（Released assets）

从 Addressables 释放内容后，它可能仍在内存中，直到所有内容从 AssetBundle 释放，以及任何依赖该 AssetBundle 中任何资源的其他 AssetBundle 也被释放。

释放的内容在内容树视图中以淡出或灰色字体颜色表示。有关 Addressables 如何 Memory management 的更多信息，请参阅内存管理。

筛选内容（Filter Content）

可以使用详细窗格中的搜索栏筛选内容名称。可以使用搜索过滤语法查找其他内容：

• Handles: h
• Type: assetType, t
• Status: s
• RefsTo: rt, r
• RefsBy: rb, p
• Source: bundlesource, bs, b

过滤语法为 <tag>:<evaluation>，其中字段是数字字段，例如handles:3。默认的等于为=。可以通过在数字前包含符号来更改等于关系为大于>或小于<，例如Handles:>2。

可以使用不带空格的列名或带有缩写 Label 进行筛选。

还可以使用类型过滤器按包含类型筛选。使用explicit表示通过 Addressables 显式包含在组中的资源，或 implicit 表示资源由于其他包含的引用而包含在 AssetBundle 中。例如，type:explicit。

Inspect Content Details

选择 Addressables Profiler 模块中的内容时，检查器会显示该内容的详细信息，如下所示：

Section	描述
Selection Details (A)	包含详细信息，包括资源的来源、加载路径、压缩格式和组。
Help (B)	包含信息，包括任何设置的提示。
References ©	包含有关引用到和从其他 AssetBundles 的信息。

Build layout report

Build layout report 提供有关 Addressables builds 的详细信息和统计数据，包括：

• AssetBundles 的描述
• 每个 Asset 和 AssetBundle 的大小
• 非 Addressable 资产作为依赖项隐式包含在 AssetBundles 中的解释。更多信息请参阅 Asset and AssetBundle dependencies 。
• AssetBundle dependencies

启用后，Addressables build 脚本会在构建 Addressables 内容时创建报告。您可以在 Preferences window 的 Addressables 部分启用该报告。您可以在项目文件夹中的 Library/com.unity.addressables/buildlayout位置找到报告。生成报告会增加构建时间。

有关构建内容的更多信息，请参阅 Building your Addressable content。

Create a Build Report

创建 build report 的步骤如下：

1. 打开 Unity Preferences 窗口（菜单：Edit > Preferences）。
2. 从偏好类型列表中选择 Addressables。
3. 启用 Debug Build Layout 选项。
4. 进行 Addressables 内容的完全构建。有关完全构建的更多信息，请参阅 Full builds。
5. 在文件系统窗口中，导航到 Unity 项目的 Library/com.unity.addressables/ 文件夹。
6. 在文本编辑器中打开 buildlayout 文件。

Report data

Build layout report 包含以下信息：

Summary section

提供构建的概述。

Name	Description
Addressable Groups	构建中包含的组的数量。
Explicit Assets Addressed	构建中 Addressable 资产的数量（不包括由 Addressable 资产引用但未标记为 Addressable 的资产）。
Total Bundle	构建创建的 AssetBundles 数量，包括包含 Scene 数据的数量。
Total Build Size	所有 AssetBundles 的总大小。
Total MonoScript Size	序列化 MonoBehaviour 和 SerializedObject 实例的大小。
Total AssetBundle Object Size	所有 AssetBundle 对象实例的大小。

Group section

报告 Addressables 如何将组中的资产打包到 AssetBundles 中。

Name	Description
Group summary	组的名称、为组创建的 bundle 数量、总大小以及为组构建的显式资产数量。
Schemas	组的架构和设置。
Asset bundles	请参阅 AssetBundle 信息。

AssetBundle Information

报告为组构建的每个 AssetBundle 的详细信息。

Name	Description
File name	AssetBundle 的文件名。
Size	AssetBundle 的大小。
Compression	bundle 使用的压缩设置。
Object size
Bundle Dependencies	当前 bundle 依赖的其他 AssetBundles 列表。这些 bundles 总是与当前 bundle 一起加载。
Expanded Bundle Dependencies
Explicit Assets	bundle 中包含的 Addressables 的资产信息。
Files	AssetBundle 存档中的文件信息。场景 bundle 每个场景最多包含两个文件，非场景 bundle 仅包含一个文件。

Asset information

提供 Explicit Assets 部分中每个资产的信息。

Name	Description
Asset path	项目中资产的路径。
Total Size
Size from Objects
Size from Streamed Data
File Index	AssetBundle 中包含此资产的文件索引。
Addressable Name	资产的地址。
External References
Internal References

File Information

提供 AssetBundle 存档（Archive）中每个序列化文件的详细信息。

Name	Description
File summary	文件列表中的索引，文件中序列化的 MonoScripts 数量和大小。
File sections	序列化文件可以有以下一个或多个部分：No extension、.resS、.resource、.sharedAssets。
Data from Other Assets	文件中资产引用的依赖资产。

Built-in bundles

列出 Addressables 从资产中创建的任何 bundle，例如默认着色器，作为 Unity 引擎的一部分提供。Addressables 构建在需要时将此类资产放入单独列出的 bundle 中，以避免在多个 bundle 中重复这些资产作为隐式依赖项。

Build profile log

Addressables 构建过程总是创建一个 .json 日志文件，包含构建性能信息。你可以在项目文件夹中的 Library/com.unity.addressables/AddressablesBuildTEP.json 找到该日志文件。

可以使用 Google Chrome 或其他基于 Chromium 的浏览器中的 chrome://tracing 工具查看该日志文件。

View the build profile

1. 打开一个基于 Chromium 的浏览器。
2. 在浏览器中输入 chrome://tracing 以打开 Trace Event Profiling Tool 。
3. 点击 Load 按钮。
4. 在文件浏览器中导航到你的 Unity 项目的 Library/com.unity.addressables 文件夹。
5. 打开 AddressablesBuildTEP.json 文件。

有关构建性能日志的更多信息，请参阅 Unity Scriptable Build Pipeline。

【参考】Addressables Report Window

Addressables Report 是一个工具，你可以用它来深入查看 Addressables Build 中构建的内容信息。

要打开 Addressables Report 窗口，前往 Window > Asset Management > Addressables 并选择 Addressables Report。

先决条件

• Addressables Report 还需要由 Addressables 构建生成的 build report 才能运行。要启用构建报告的生成，前往 Edit > Preferences > Addressables 并启用 Debug Build Layout。
• 默认情况下，Addressables Report 会在每次构建后自动打开。要禁用此功能，前往 Edit > Preferences > Addressables 并禁用 Open Addressables Report After Build。

Addressables Report 窗口概览

Addressables Report 窗口具有以下视图：

视图	描述
Summary tab	显示 Addressables 构建及其内容的高级概述。
Explore tab	显示作为 Addressables 构建一部分构建的所有内容的详细细分。
Potential Issues tab	扫描当前构建报告中的可能影响构建性能或其他不理想的潜在问题。
在 Addressables Report 窗口顶部选择 tab 以在视图之间切换。

左侧边栏面板包含项目中检测到的所有构建报告的列表。选择侧边栏中的构建报告以在 Addressables Report 窗口中加载该报告。

右侧边栏是 Inspector Panel ，你可以在 Explore 或 Potential Issues 视图中查看有关资产或 AssetBundle 的详细信息。

在 Build Report 窗口中使用搜索栏在 Explore 和 Potential Issues tab 中进行搜索。这将按搜索栏中的文本过滤当前视图中的所有资产。

Summary tab

Summary tab 显示选定构建报告的信息，以及有关构建中检测到的潜在问题的信息。它包括以下部分：

• General Information：包括构建创建的 catalogs 位置、当前构建使用的 profile、构建所用时间，以及创建构建的 Addressables 包和 Unity Editor 的版本。
• Potential Issues：包含 Potential Issues tab 中的问题摘要。
• Aggregate Information：显示作为构建一部分创建的 AssetBundles 数量、构建的 bundles 大小以及构建中的资产数量。资产数量包括由 Addressable 资产引用但未标记为 Addressable 的资产。这些资产必须包含在构建中，以允许加载依赖它们的资产。

如果不同 bundles 中的多个 Addressable 资产依赖于同一个非 Addressable 资产，则该非 Addressable 资产将在多个 bundles 中重复。有关重复资产的更多信息，请参阅 Duplicated Assets View。

Explore Tab

Explore tab 包含选定构建报告的详细信息。使用View By下拉菜单更改在构建报告中资产的组织方式。

可以按以下方式对 Explore View 进行排序：

视图	描述
AssetBundles	显示作为 Addressables 构建一部分构建的所有 AssetBundles。展开一个 AssetBundle 以显示该 bundle 包含的资产。这是默认视图。
Assets	显示作为 Addressables 构建一部分构建的所有资产。展开一个资产以显示所有依赖于该资产的资产和 AssetBundles。
Labels	显示作为 Addressables 构建一部分构建的所有资产，按附加到资产的 label 排序。展开一个资产以显示依赖于该资产的资产和 AssetBundles 。
Groups	显示作为 Addressables 构建一部分构建的所有 AssetBundles，按生成该 bundle 的 Group 进行排序。如果你使用 Pack Together By Label 或 Pack Separately 组设置，一个组可能会生成多个 AssetBundles。

在 Explore Tab 中选择一个资产时，其信息会显示在 Inspector 面板中。

Potential Issues Tab

Potential Issues tab 扫描选定的构建报告中的潜在问题或问题，这些问题可能在构建过程中发生。你可以查看这些问题可能发生的原因。它具有以下视图：

• Duplicated Assets View：显示构建中在多个 bundles 之间重复的所有非 Addressable Assets 的列表。这发生在两个 Addressable 资产位于不同的 bundles 中，但都引用了一个未标记为 Addressable 的公共资产时。

要解决这些问题，可以将 Addressable Assets 移动到同一个 bundle 中，或使 Assets 成为 addressable。两种方法都会对构建依赖关系产生影响。通常应使用最小化资产重复影响的方法。

在 Potential Issues Tab 中选择一个资产时，会在 Inspector 面板中打开其信息。

【参考】Addressables Report Inspector

你可以使用 Inspector 查看任何特定资产或 AssetBundle 的深入信息。当你在 Explore 标签或 Potential Issues 标签中选择一个资产或 AssetBundle 时，Inspector 面板会显示有关选定 Asset 或 AssetBundle 的信息。

Inspector 面板部分

Inspector 面板包含以下部分：

Summary Panel

使用此面板中的按钮执行以下操作：

• Select in Editor：在 Unity Editor 中选择该 Asset 。
• Select in Group：在 Explore 窗口的 Groups 视图中选择该 Asset 。如果你当前不在 Groups 视图，它将导航到该视图。
• Select in Bundle：在 Explore 窗口的 AssetBundles 视图中选择该 Asset 。如果你当前不在 AssetBundles 视图，它将导航到该视图。
• Search in this view：在搜索栏中搜索该资产的名称。

References Panel

References 面板有以下标签：

• References To：包含选定项所依赖的所有资产和 AssetBundles 的列表。例如，如果你有一个引用了 shader 的材质，那么在 Explore 视图中选择材质时，shader 会出现在这个标签中。
• Referenced By：包含依赖于选定项的所有资产和 AssetBundles 的列表。例如，如果你有一个引用了 shader 的材质，那么在 Explore 视图中选择 shader 时，该 shader 引用的材质会出现在这个标签中。
  

在 References 面板中选择一个资产或 AssetBundle 旁边的箭头，以遍历顶级资产的依赖关系。例如，在上图中，Table 依赖于 bundle defaultlocalgroup_assets_all。选择箭头会显示生成此依赖关系的资产是 TableMaterial，并且 defaultlocalgroup_assets_all bundle 还包含另外三个不是 Table 依赖项的资产。

对于不是 Addressable 但被另一个 Addressable asset 引入 bundle 的 asset ，问号图标会显示在这些 asset 旁边。选择它以高亮显示同一 bundle 中引用该 asset 的所有 asset 。

参考

1. com.unity.addressables
2. github.com/Unity-Technologies/Addressables-Sample
3. https://blog.unity.com/engine-platform/addressables-planning-and-best-practices
4. Why use Addressables? - Unity Learn course.