前言:

Unity Assembly Definition（程序集定义）是Unity 2017.3版本引入的一项重要功能，它彻底改变了Unity项目中代码的组织和编译方式。本文将全面深入地讲解Assembly Definition的概念、工作原理、创建使用方法、最佳实践以及常见问题解决方案，帮助你掌握这一提升项目效率的强大工具。

一、Assembly Definition 基础概念

1.1 什么是Assembly Definition？

Assembly Definition（程序集定义，文件扩展名为.asmdef）是Unity用于定义和管理C#程序集的配置文件。通过它，开发者可以将项目代码划分为多个独立的程序集（Assembly），而不是默认将所有脚本编译到单一的程序集中。

程序集在C#中是一个基本概念，它是代码的编译单元，包含编译后的类、结构体等类型，并定义了对其他程序集的引用关系。在Unity中，程序集最终会被编译为DLL文件。

1.2 为什么需要Assembly Definition？

在引入Assembly Definition之前，Unity项目默认将所有脚本编译到几个预定义程序集中（如Assembly-CSharp.dll），这带来了几个明显问题：

1. 编译效率低下：修改任何一个脚本都会导致整个程序集重新编译，项目越大编译时间越长
2. 代码耦合度高：所有脚本可以相互访问，缺乏明确的依赖关系管理
3. 平台针对性差：所有脚本都会为所有平台编译，无法针对特定平台优化
4. 代码复用困难：难以将特定功能模块提取出来用于其他项目

Assembly Definition通过模块化代码解决了这些问题，让开发者能够更精细地控制代码组织和编译过程

1.3 Unity的预定义程序集

即使不使用自定义Assembly Definition，Unity也会按照一定规则将脚本分配到4个预定义程序集中：

编译阶段	程序集名称	包含的脚本位置
1	Assembly-CSharp-firstpass	Plugins、Standard Assets下的运行时脚本
2	Assembly-CSharp-Editor-firstpass	Plugins/Editor、Standard Assets/Editor下的脚本
3	Assembly-CSharp	其他不在Editor目录下的普通脚本
4	Assembly-CSharp-Editor	所有Editor目录下的脚本

这些程序集的编译顺序是固定的，后编译的程序集可以引用先编译的程序集，但反之则不行。

二、Assembly Definition 的核心优势

使用Assembly Definition能为Unity项目带来多方面的显著好处：

2.1 大幅减少编译时间

通过将代码分割到多个程序集中，当修改某个脚本时，只有它所在的程序集及直接依赖它的程序集需要重新编译，其他独立程序集则不需要。这对于大型项目可以显著提高迭代效率。

示例：假设项目有三个程序集：Core（核心）、Gameplay（游戏逻辑）、UI（用户界面）。当只修改UI相关脚本时，只有UI程序集需要重新编译，Core和Gameplay则不需要。

2.2 改善代码组织结构

Assembly Definition强制开发者思考代码的模块划分和依赖关系，自然地促使项目形成更清晰的架构。不同功能的代码被划分到不同程序集中，降低了意外的耦合。

2.3 精确控制代码可见性

程序集间只能访问明确引用的公开类型，这相当于提供了一种"物理"层面的访问控制，比单纯的命名空间划分更严格。

2.4 更好的代码复用

独立的功能模块可以更容易地提取出来，用于其他项目。只需将对应的程序集DLL文件复制到新项目即可。

2.5 平台特定代码管理

可以为不同平台创建不同的程序集，在构建时只包含目标平台所需的代码。

三、创建和使用Assembly Definition

3.1 创建Assembly Definition的基本步骤

1. 规划代码结构：根据功能划分模块，确定哪些代码应该放在一起

2. 创建文件夹：在Assets下为每个模块创建单独的文件夹

3. 创建.asmdef文件：

   • 右键点击文件夹
   • 选择 Create > Assembly Definition
   • 输入有意义的名称（如"Gameplay.Core"）

4. 配置属性：在Inspector面板中设置程序集的各种选项

5. 设置依赖关系：为需要引用其他程序集的.asmdef添加引用

3.2 Assembly Definition的详细配置

创建.asmdef文件后，可以在Inspector面板中配置以下属性：

基本设置

• Name：程序集名称，在整个项目中必须唯一
• Root Namespace：设置默认命名空间，新建脚本时会自动添加该命名空间

常规选项

• Allow ‘unsafe’ Code：允许使用unsafe代码（如指针操作）
• Auto Referenced：是否让预定义程序集自动引用此程序集
• No Engine References：禁用对UnityEngine和UnityEditor的自动引用
• Override References：手动指定要引用的预编译程序集

平台设置

• Include Platforms：指定只在哪些平台上包含此程序集
• Exclude Platforms：指定在哪些平台上排除此程序集

依赖管理

• Assembly Definition References：添加对其他程序集定义的引用
• Version Defines：基于包版本的条件编译

3.3 设置程序集依赖关系

程序集之间的引用是单向的，必须明确设置才能访问其他程序集中的类型：

1. 选中需要添加引用的.asmdef文件
2. 在Inspector中找到"Assembly Definition References"部分
3. 点击"+"按钮或直接拖拽其他.asmdef文件到引用列表中
4. 点击"Apply"保存更改

重要规则：

• 避免循环引用（A引用B，B又引用A）
• 引用关系不可传递（A引用B，B引用C，不意味着A能访问C）
• 只能访问被引用程序集中的public类型

3.4 多层级的Assembly Definition管理

当文件夹结构有嵌套时，Assembly Definition的归属遵循"最短路径"原则：

• 脚本属于离它最近（文件夹层级最少）的.asmdef文件
• 如果脚本所在文件夹及其父文件夹都没有.asmdef，则属于默认的Assembly-CSharp
• 可以通过选中脚本，在Inspector面板查看它属于哪个程序集

示例：

Assets/
  Scripts/
    Core.asmdef
    Core/
      Math.cs          # 属于Core程序集
      AI/
        Pathfinding.cs # 属于Core程序集
    Gameplay/
      Characters.asmdef
      Characters/
        Player.cs      # 属于Characters程序集
      Items.cs         # 属于Assembly-CSharp（父文件夹无.asmdef）

四、Assembly Definition 高级用法

4.1 模块化开发实践

使用Assembly Definition可以实现真正的模块化开发，每个功能模块作为独立程序集：

// Core模块
namespace MyGame.Core
{
    public class GameManager { ... }
}

// AI模块
namespace MyGame.AI
{
    public class BehaviorTree { ... }
}

// UI模块 
namespace MyGame.UI
{
    public class HudController { ... }
}

对应的.asmdef引用关系：

• UI.asmdef 引用 Core.asmdef
• AI.asmdef 引用 Core.asmdef
• 主程序集 引用 UI.asmdef 和 AI.asmdef

这种结构确保核心功能被集中管理，各模块通过明确接口通信。

4.2 处理第三方库

将第三方库放入单独程序集是推荐做法：

1. 在Plugins文件夹下为每个重要第三方库创建子文件夹
2. 为每个库添加.asmdef文件（如"Dotween.asmdef"）
3. 主程序按需引用这些库程序集

这样做的好处：

• 隔离第三方代码变更影响
• 清晰区分自有代码和外部代码
• 便于替换或更新库版本

4.3 平台特定代码处理

通过Platforms设置，可以为不同平台创建专属程序集37：

// 主程序集
public abstract class PlatformAPI { ... }

// Android程序集（只在Android平台包含）
[assembly: IncludePlatforms("Android")]
public class AndroidPlatformAPI : PlatformAPI { ... }

// iOS程序集（只在iOS平台包含）
[assembly: IncludePlatforms("iOS")]
public class IOSPlatformAPI : PlatformAPI { ... }

在构建时，Unity会自动只包含目标平台对应的程序集。

4.4 程序集与脚本编译顺序

Unity按照以下顺序编译程序集：

1. 预编译程序集（如UnityEngine.dll）
2. 自定义程序集（按依赖顺序）
3. Assembly-CSharp-firstpass
4. Assembly-CSharp-Editor-firstpass
5. Assembly-CSharp
6. Assembly-CSharp-Editor

自定义程序集的编译顺序由它们的依赖关系决定，被依赖的程序集会先编译。

五、最佳实践与常见问题

5.1 Assembly Definition最佳实践

1. 全有或全无：要么对所有脚本使用Assembly Definition，要么完全不用。混合使用会削弱其优势37

2. 合理划分模块：

   • 按功能而非类型划分（如"AI"、“UI"而非"Scripts”、“Models”）
   • 核心基础功能放在底层程序集
   • 避免程序集过多导致管理复杂910

3. 命名规范：

   • 程序集名称使用PascalCase
   • 包含项目前缀（如"MyGame.Core"）
   • 保持与文件夹结构一致

4. 依赖管理：

   • 尽量减少程序集间交叉引用
   • 核心程序集应保持最小依赖
   • 使用接口减少直接类型依赖710

5. 测试策略：

   • 为测试代码创建单独程序集
   • 测试程序集引用被测试程序集
   • 使用InternalsVisibleTo共享internal类型给测试

5.2 常见问题与解决方案

问题1：类型找不到（CS0246错误）

• 原因：未添加必要的程序集引用
• 解决：检查类型所在程序集，在依赖程序集中添加引用18

问题2：循环依赖

• 现象：编译错误"Assembly A references Assembly B which references Assembly A"

• 解决：

  1. 提取公共代码到第三个程序集
  2. 使用接口减少直接依赖
  3. 重新设计模块划分410

问题3：编辑器代码被打包

• 原因：Editor代码未放在Editor文件夹或未设置平台过滤

• 解决：

  1. 确保编辑器代码放在Editor文件夹
  2. 为编辑器程序集设置"Include Platforms"为"Editor"6

问题4：脚本归属不明确

• 现象：脚本被分配到意外的程序集

• 解决：

  1. 检查文件夹结构，确保.asmdef在正确位置
  2. 使用Inspector确认脚本实际所属程序集
  3. 调整.asmdef文件位置37

问题5：反射找不到类型

• 原因：反射时默认只在调用者程序集中查找

• // 明确指定程序集
  var type = Assembly.Load("MyGame.Core").GetType("MyGame.Core.GameManager");
  

六、实战案例：重构现有项目

让我们通过一个实际案例，看看如何将传统Unity项目迁移到使用Assembly Definition的结构。

6.1 原始项目结构

Assets/
└── Scripts/
    ├── Managers/
    │   ├── GameManager.cs
    │   └── UIManager.cs
    ├── Player/
    │   ├── PlayerController.cs
    │   └── PlayerInventory.cs
    ├── AI/
    │   ├── EnemyController.cs
    │   └── BehaviorTree.cs
    └── Utilities/
        ├── MathHelper.cs
        └── Extensions.cs

6.2 重构步骤

1. 分析依赖关系：

   • GameManager被大多数脚本依赖
   • MathHelper和Extensions是通用工具
   • Player和AI模块相对独立

2. 创建程序集结构：

   Assets/
   ├── Core/
   │   ├── Core.asmdef
   │   ├── Managers/
   │   │   └── GameManager.cs
   │   └── Utilities/
   │       ├── MathHelper.cs
   │       └── Extensions.cs
   ├── Gameplay/
   │   ├── Player.asmdef (→ Core)
   │   ├── Player/
   │   │   ├── PlayerController.cs
   │   │   └── PlayerInventory.cs
   │   ├── AI.asmdef (→ Core)
   │   └── AI/
   │       ├── EnemyController.cs
   │       └── BehaviorTree.cs
   └── UI/
       ├── UI.asmdef (→ Core)
       └── UIManager.cs
   

   1. 配置程序集属性：

      • Core.asmdef：设置Root Namespace为"MyGame.Core"
      • 其他程序集添加对Core的引用

   2. 处理特殊情况：

      • 如果有编辑器扩展，创建Editor文件夹并添加Editor.asmdef
      • 第三方库移动到Plugins文件夹并添加对应.asmdef

6.3 重构后的优势

1. 修改AI代码不会触发Player或UI代码重新编译
2. Core模块可以轻松共享给其他项目
3. 代码结构更清晰，依赖关系明确
4. 可以针对不同平台构建不同模块

七、Assembly Definition底层原理

理解Assembly Definition的工作原理有助于更好地使用它。

7.1 Unity编译流程

当使用Assembly Definition时，Unity的编译流程变为46：

1. 收集所有.asmdef文件并分析依赖关系
2. 为每个程序集创建临时.csproj文件
3. 调用Roslyn编译器按依赖顺序编译各程序集
4. 生成DLL文件到Library/ScriptAssemblies
5. 将DLL加载到Unity运行时

7.2 程序集与预编译符号

Assembly Definition可以与自定义预编译符号结合使用310：

// 在.asmdef的Define Constraints中添加"MY_CONDITION"
#if MY_CONDITION
    // 条件编译代码
#endif

这在需要针对不同环境编译不同代码时非常有用。

7.3 程序集版本控制

通过Version Defines可以基于包版本进行条件编译10：

// 在.asmdef中
"versionDefines": [
    {
        "name": "com.unity.addressables", 
        "expression": "1.20.0",
        "define": "ADDRESSABLES_1_20_OR_NEWER"
    }
]

八、总结

Unity Assembly Definition是一项强大的代码组织工具，它能显著提升大型项目的开发效率。通过合理划分程序集，开发者可以获得以下收益：

1. 更快的编译时间：减少不必要的重新编译
2. 更清晰的架构：强制思考模块边界和依赖
3. 更好的代码复用：模块可以跨项目共享
4. 更精确的平台控制：针对不同平台包含不同代码

开始使用Assembly Definition的最佳方式是逐步重构现有项目：从核心功能开始，逐步将代码迁移到独立的程序集中。虽然初期需要一些投入，但随着项目规模增长，这种投入会带来丰厚的回报。

记住Assembly Definition的核心原则：明确依赖、避免循环、最小暴露。遵循这些原则，你就能构建出更健壮、更易维护的Unity项目。

转载自CSDN-专业IT技术社区

版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

原文链接：https://blog.csdn.net/qq_38358224/article/details/149798502