1. 项目概述：为什么我们需要运行时代码动态加载？

如果你在Unity开发中遇到过这样的场景：游戏启动时，因为要编译和加载海量脚本，导致编辑器卡顿、真机启动黑屏时间过长，或者想在游戏上线后，不更新客户端就能修复Bug、添加新功能，那么“运行时代码动态加载”就是你必须要掌握的核心技能。这不仅仅是性能优化，更是现代游戏，尤其是需要热更新、内容动态化的手游和大型项目的架构基石。

传统的Unity开发流程是“编辑时编译，运行时加载”。所有C#脚本在点击播放按钮前，由Unity编辑器（或CI流水线）调用Mono或IL2CPP编译器一次性编译成DLL，打包进游戏。运行时，这些代码是静态的、不可变的。而“运行时代码动态加载”打破了这一限制，它允许我们在游戏运行过程中，从网络、本地文件或其他来源，动态地读取、编译并执行新的C#代码。这就像给你的游戏装上了一颗可以随时“换零件”甚至“升级大脑”的引擎。

实现这一目标，绕不开两个核心挑战：异步与编译。Unity的主线程是单线程的，同步编译大量代码会直接卡死游戏循环。而C#代码从文本到可执行，需要经过编译器的处理。本指南将聚焦于使用UniTask这一强大的异步库，来优雅地解决异步问题，并深入拆解Unity环境下的动态编译技术，为你呈现一套从原理到落地的“终极”解决方案。

2. 核心原理与架构设计

2.1 动态代码加载的底层逻辑

在Unity中实现运行时代码加载，本质上是利用了.NET框架的System.CodeDom.Compiler命名空间和System.Reflection（反射）机制。其核心流程可以概括为以下几步：

1. 源代码获取：从目标来源（如AssetBundle、Addressables、网络服务器、本地文本文件）读取C#源代码字符串。
2. 编译器配置：创建一个C#代码编译器（通常是CSharpCodeProvider），并为其配置必要的编译参数。这些参数至关重要，包括：
   • 引用程序集：你的动态代码可能需要访问UnityEngine.dll、UnityEditor.dll（仅在编辑器下）、你项目中的其他DLL，以及.NET标准库。必须将所有依赖的程序集路径明确告知编译器。
   • 编译器选项：例如目标平台（/target:library生成DLL）、优化级别、是否生成调试信息等。
3. 异步编译：将源代码和配置提交给编译器，启动编译过程。这是一个典型的I/O密集型兼CPU密集型操作，必须异步执行，否则会阻塞主线程。
4. 程序集加载与反射：编译成功后，会得到一个内存中的程序集（Assembly对象）或一个物理DLL文件。通过Assembly.Load（或LoadFrom）将其加载到当前的应用程序域（AppDomain）中。
5. 实例化与调用：利用反射，从加载的程序集中查找特定的类型（Class），创建其实例，并调用其方法。为了获得更好的性能，通常会将反射得到的MethodInfo缓存起来。

注意：在IL2CPP环境下，动态代码生成和加载受到严格限制。标准的CodeDom编译在AOT（预先编译）的IL2CPP运行时可能无法工作。通常，动态加载的方案主要应用于开发阶段、编辑器扩展，或者通过HybridCLR等热更新方案来支持。本指南主要探讨在Mono后端和编辑器环境下的通用实现。

2.2 为什么是UniTask？对比协程与原生async/await

Unity传统的异步编程方式是协程（IEnumerator+yield return）。它在处理简单时序逻辑时很直观，但存在明显缺陷：

• 错误处理困难：协程内部异常无法被外部try-catch直接捕获，容易导致静默失败。
• 组合性差：难以等待多个协程同时完成，或进行复杂的流程控制（如超时、取消）。
• 性能开销：每次yield return都会产生一个小的GC Alloc（垃圾分配），在频繁使用时对性能不友好。

C#原生的async/await语法是现代异步编程的标杆，但在Unity旧版本或某些深度优化场景下，其默认的Task类可能并非最佳选择，因为它与Unity的生命周期（如MonoBehaviour.Update）结合不够紧密。

UniTask应运而生，它完美地融合了二者的优点：

• 零分配（Zero Allocation）：UniTask提供了值类型（struct）的Task，大量操作避免了堆内存分配，对性能敏感的游戏循环至关重要。
• 深度Unity集成：提供了UniTask.Delay、UniTask.Yield等直接返回PlayerLoop时间点的等待，以及UniTask.WaitUntil等与Unity状态紧密结合的API。
• 强大的工具链：内置了UniTask.WhenAll、UniTask.WhenAny、超时（Timeout）、取消（CancellationToken）等高级控制流，并且错误传播符合直觉。
• 友好的调试：相比协程，async/await的调用栈在调试时清晰得多。

在动态编译这个场景中，编译过程耗时不确定，我们需要一个能够优雅处理取消、超时，并且不卡顿主线程的异步方案。UniTask的async/await写法能让我们的代码看起来像同步一样简洁，同时具备工业级的健壮性。

2.3 系统架构设计图（概念）

一个健壮的动态代码加载系统通常包含以下模块：

[源代码存储层] (网络/CDN/本地/AssetBundle) | v [源代码获取器] (异步下载/加载文本) | v [编译服务核心] (配置编译器、引用管理、异步编译) <-- 核心，使用UniTask驱动 | v [程序集管理器] (加载、缓存、卸载Assembly) | v [类型工厂/接口契约] (通过反射创建实例，转换为约定接口) | v [游戏业务层] (调用动态代码实现的功能)

设计关键：业务层不应直接依赖具体的动态类型，而应依赖一个预先定义好的接口（Interface）。动态编译的类需要实现这个接口。这样，系统就实现了彻底的解耦，业务逻辑只知道接口，不关心实现是从何而来。

3. 一步步实现UniTask异步动态编译

3.1 环境准备与UniTask安装

首先，确保你的项目已准备好。我们通过Unity的Package Manager来安装UniTask，这是最推荐的方式。

1. 打开Unity编辑器，点击顶部菜单Window > Package Manager。
2. 在Package Manager窗口，点击左上角的“+”按钮，选择“Add package from git URL...”。
3. 输入UniTask的Git仓库地址：https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask
4. 点击“Add”。等待Unity下载并导入包。

实操心得：也可以从Asset Store下载，但通过Git URL安装能确保获取到最新版本。如果你的项目需要锁定特定版本，可以在项目的Packages/manifest.json文件中将Git URL改为带有版本标签的地址，例如https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask#2.3.1。

3.2 定义代码契约（接口）

在项目的静态代码部分（即常规的Scripts目录下），定义一个或多个接口。所有动态加载的代码都必须实现这些接口。

// 文件：IDynamicModule.cs // 放置于 Assets/Scripts/Contracts/ 目录下 public interface IDynamicModule { // 模块初始化方法，可以传递一些上下文数据 UniTask InitializeAsync(GameContext context); // 模块主逻辑方法 void ExecuteLogic(); // 模块清理方法 UniTask CleanupAsync(); } // 一个上下文数据示例 public class GameContext { public int PlayerLevel { get; set; } public SomeService Service { get; set; } }

这样，无论动态代码里写了什么，我们最终只需要调用IDynamicModule定义的方法。

3.3 构建异步编译服务核心

这是最核心的类，我们将其命名为DynamicCodeCompiler。

// 文件：DynamicCodeCompiler.cs using System; using System.CodeDom.Compiler; using System.Collections.Generic; using System.IO; using System.Linq; using System.Reflection; using System.Threading; using Cysharp.Threading.Tasks; using Microsoft.CSharp; using UnityEngine; public class DynamicCodeCompiler { // 单例模式，便于全局访问 private static DynamicCodeCompiler _instance; public static DynamicCodeCompiler Instance => _instance ??= new DynamicCodeCompiler(); // 编译器实例 private CSharpCodeProvider _codeProvider; // 编译器参数 private CompilerParameters _compilerParams; private DynamicCodeCompiler() { InitializeCompiler(); } private void InitializeCompiler() { _codeProvider = new CSharpCodeProvider(); _compilerParams = new CompilerParameters(); // 1. 生成内存中的DLL，不输出文件 _compilerParams.GenerateInMemory = true; // 2. 不生成调试信息（发布时设为false以提升性能） _compilerParams.IncludeDebugInformation = true; // 3. 添加关键引用：Unity核心库 _compilerParams.ReferencedAssemblies.Add(Assembly.GetAssembly(typeof(MonoBehaviour)).Location); // UnityEngine.dll // 4. 添加.NET基础库 _compilerParams.ReferencedAssemblies.Add("System.dll"); _compilerParams.ReferencedAssemblies.Add("System.Core.dll"); // 5. 添加项目自身程序集引用（这是关键且容易遗漏的一步！） // 我们需要引用当前已运行游戏的所有DLL，以便动态代码能访问项目中的其他类。 // 注意：在编辑器下和打包后，程序集的位置和名称可能不同。 AddCurrentDomainAssemblies(); } private void AddCurrentDomainAssemblies() { // 获取当前AppDomain中的所有已加载程序集 var loadedAssemblies = AppDomain.CurrentDomain.GetAssemblies(); foreach (var assembly in loadedAssemblies) { try { // 过滤掉系统核心库和动态生成的程序集，避免重复或冲突 if (!assembly.IsDynamic && !string.IsNullOrEmpty(assembly.Location)) { // 避免重复添加UnityEngine等 if (!_compilerParams.ReferencedAssemblies.Contains(assembly.Location)) { // 特别注意：要引用包含我们契约接口(IDynamicModule)的程序集 _compilerParams.ReferencedAssemblies.Add(assembly.Location); } } } catch (NotSupportedException) { // 某些程序集（如动态生成的）可能没有Location，忽略即可 } } } /// <summary> /// 异步编译C#源代码字符串，并返回指定类型的实例。 /// </summary> /// <typeparam name="T">约定的接口类型，如IDynamicModule</typeparam> /// <param name="sourceCode">C#源代码</param> /// <param name="typeName">要实例化的完整类型名（命名空间.类名）</param> /// <param name="cancellationToken">用于取消编译的令牌</param> /// <returns>编译并实例化的对象</returns> public async UniTask<T> CompileAndCreateInstanceAsync<T>(string sourceCode, string typeName, CancellationToken cancellationToken = default) where T : class { // 使用UniTask切换到后台线程池执行编译，避免阻塞主线程 CompilerResults compileResult = await UniTask.RunOnThreadPool(() => { return _codeProvider.CompileAssemblyFromSource(_compilerParams, sourceCode); }, cancellationToken: cancellationToken); // 检查编译错误 if (compileResult.Errors.HasErrors) { var errorMsg = string.Join("\n", compileResult.Errors.Cast<CompilerError>().Select(e => e.ToString())); throw new Exception($"动态编译失败:\n{errorMsg}"); } // 从编译结果中获取程序集 Assembly assembly = compileResult.CompiledAssembly; // 使用反射查找并创建类型实例 Type targetType = assembly.GetType(typeName); if (targetType == null) { throw new Exception($"在动态程序集中未找到类型: {typeName}"); } object instance = Activator.CreateInstance(targetType); if (!(instance is T result)) { throw new Exception($"类型 {typeName} 未实现接口 {typeof(T).Name}"); } return result; } }

关键点解析：

• UniTask.RunOnThreadPool: 这是将阻塞性操作（编译）卸载到线程池的关键。它返回一个UniTask，完美融入async/await流程。
• 引用管理：AddCurrentDomainAssemblies方法动态添加引用，确保了动态代码能访问到项目内其他类。这是实现“动态代码调用静态代码”的基础。
• 错误处理：编译错误被收集并包装成异常抛出，符合async/await的错误传播模型。
• 泛型约束：方法要求返回类型T是class，并通过as转换确保类型安全。

3.4 实现源代码的异步获取

编译服务准备好了，我们还需要一个获取源代码的模块。这里以从本地Resources文件夹加载文本文件为例，演示如何用UniTask封装Unity的异步资源加载。

// 文件：DynamicCodeLoader.cs using Cysharp.Threading.Tasks; using UnityEngine; public static class DynamicCodeLoader { /// <summary> /// 从Resources文件夹异步加载C#脚本文本。 /// </summary> public static async UniTask<string> LoadSourceFromResourcesAsync(string pathWithoutExtension) { // Unity的Resource.Load是同步的，我们用UniTask.ToUniTask将其转换为UniTask var resourceRequest = Resources.LoadAsync<TextAsset>(pathWithoutExtension); // 等待加载完成 TextAsset textAsset = await resourceRequest.ToUniTask(); if (textAsset == null) { throw new System.IO.FileNotFoundException($"未在Resources中找到代码文件: {pathWithoutExtension}"); } return textAsset.text; } /// <summary> /// 从网络URL异步下载C#脚本文本。 /// </summary> public static async UniTask<string> DownloadSourceFromWebAsync(string url, CancellationToken cancellationToken = default) { // 使用UnityWebRequest，并用UniTask封装 using (var webRequest = UnityEngine.Networking.UnityWebRequest.Get(url)) { await webRequest.SendWebRequest().ToUniTask(cancellationToken: cancellationToken); #if UNITY_2020_3_OR_NEWER if (webRequest.result != UnityEngine.Networking.UnityWebRequest.Result.Success) #else if (webRequest.isNetworkError || webRequest.isHttpError) #endif { throw new System.Exception($"下载代码失败: {webRequest.error}, URL: {url}"); } return webRequest.downloadHandler.text; } } }

注意：Resources.LoadAsync在WebGL等平台可能并非真正的异步。对于生产环境，更推荐使用Addressables或AssetBundle系统进行资源加载，它们为各种平台提供了更一致的异步加载体验。用UniTask封装Addressables.LoadAssetAsync的方法类似。

3.5 整合：完整的动态模块加载流程

现在，我们将所有部分串联起来，在一个MonoBehaviour中展示完整的调用流程。

// 文件：DynamicModuleManager.cs using Cysharp.Threading.Tasks; using UnityEngine; using System.Threading; public class DynamicModuleManager : MonoBehaviour { public string dynamicCodePathInResources = "DynamicCode/MyDynamicLogic"; // Resources下的路径 public string expectedTypeName = "MyNamespace.MyDynamicClass"; // 动态代码中的完整类名 private IDynamicModule _currentModule; private CancellationTokenSource _cancellationTokenSource; async void Start() { await LoadAndRunDynamicModule(); } void OnDestroy() { // 确保在对象销毁时取消正在进行的异步操作 _cancellationTokenSource?.Cancel(); _cancellationTokenSource?.Dispose(); if (_currentModule != null) { // 注意：清理也应该是异步的，这里简化为同步等待，生产环境需处理 _currentModule.CleanupAsync().Forget(); } } private async UniTask LoadAndRunDynamicModule() { _cancellationTokenSource = new CancellationTokenSource(); var ct = _cancellationTokenSource.Token; try { Debug.Log("开始加载动态代码..."); // 1. 异步获取源代码 string sourceCode = await DynamicCodeLoader.LoadSourceFromResourcesAsync(dynamicCodePathInResources); Debug.Log("开始编译动态代码..."); // 2. 异步编译并创建实例，设置5秒超时 _currentModule = await DynamicCodeCompiler.Instance .CompileAndCreateInstanceAsync<IDynamicModule>(sourceCode, expectedTypeName, ct) .Timeout(TimeSpan.FromSeconds(5)); // UniTask的超时扩展 Debug.Log("动态模块编译成功，开始初始化..."); // 3. 初始化动态模块 var context = new GameContext { PlayerLevel = 10 }; await _currentModule.InitializeAsync(context); Debug.Log("执行动态模块逻辑..."); // 4. 执行模块逻辑（假设是同步方法） _currentModule.ExecuteLogic(); } catch (System.OperationCanceledException) when (ct.IsCancellationRequested) { Debug.LogWarning("动态模块加载被取消。"); } catch (System.TimeoutException) { Debug.LogError("动态模块编译超时！"); } catch (System.Exception e) { Debug.LogError($"动态模块加载失败: {e.Message}"); Debug.LogException(e); // 输出完整堆栈 } } // 提供一个按钮或外部调用来重新加载 [ContextMenu("重新加载动态模块")] public void ReloadModule() { _cancellationTokenSource?.Cancel(); // 取消之前的加载 LoadAndRunDynamicModule().Forget(); // 启动新的加载，.Forget()表示不等待 } }

4. 高级技巧、性能优化与避坑指南

4.1 程序集缓存与卸载

反复编译相同的代码是巨大的性能浪费。我们应该缓存已编译的程序集。

public class DynamicCodeCompiler { // ... 其他代码 ... private Dictionary<string, Assembly> _assemblyCache = new Dictionary<string, Assembly>(); public async UniTask<T> CompileAndCreateInstanceAsync<T>(string sourceCode, string typeName, CancellationToken ct = default) where T : class { // 生成一个简单的哈希键（生产环境可用更健壮的哈希算法如MD5） string cacheKey = $"{sourceCode.GetHashCode()}_{typeName}"; if (!_assemblyCache.TryGetValue(cacheKey, out Assembly assembly)) { // 未命中缓存，执行编译... CompilerResults compileResult = await UniTask.RunOnThreadPool(() => {...}, ct); // ... 检查错误 assembly = compileResult.CompiledAssembly; _assemblyCache[cacheKey] = assembly; // 存入缓存 Debug.Log($"编译并缓存程序集: {cacheKey}"); } else { Debug.Log($"使用缓存的程序集: {cacheKey}"); } // ... 后续反射创建实例逻辑不变 } }

卸载问题：在.NET中，一旦程序集加载到AppDomain，就无法直接卸载。但你可以卸载整个AppDomain。在Unity中，这通常意味着重启游戏。因此，动态加载的代码要谨慎管理生命周期，避免频繁加载大量不同代码导致内存泄漏。对于需要更新的代码，可以设计版本号，通过缓存键区分。

4.2 依赖管理与引用冲突

动态代码依赖项目内的其他DLL。如果项目使用了程序集定义文件（Assembly Definition Files, asmdef），情况会复杂一些。

• 确保引用传递：你的动态编译服务所在的程序集，必须引用所有动态代码可能用到的程序集。编译器参数中的ReferencedAssemblies需要包含这些asmdef编译后的DLL路径。你可以通过Assembly.GetAssembly(typeof(SomeTypeInTargetAsmdef)).Location来获取路径。
• 版本冲突：避免动态代码引用与宿主环境不同版本的DLL。确保使用项目统一的依赖。

4.3 在编辑器下的特殊处理与调试

在Unity编辑器中运行，你可以利用UnityEditor命名空间下的API获得更多能力，比如直接访问AssetDatabase来获取源代码文件。

#if UNITY_EDITOR using UnityEditor; public static async UniTask<string> LoadSourceInEditorAsync(string assetPath) { // assetPath 如 "Assets/Scripts/Dynamic/MyCode.cs" TextAsset textAsset = AssetDatabase.LoadAssetAtPath<TextAsset>(assetPath); if (textAsset == null) throw new FileNotFoundException(...); return textAsset.text; } #endif

调试动态代码：如果编译时设置了IncludeDebugInformation = true，并且你的源代码文件在磁盘上路径可访问，理论上可以下断点。但过程比较麻烦。更实用的调试方法是日志输出。确保你的动态代码可以通过Debug.Log或一个注入的日志接口来输出信息。

4.4 常见问题排查表

4.5 安全性与沙箱考量

警告：执行来自网络或用户输入的代码是极度危险的行为。恶意代码可以访问文件系统、网络、甚至格式化磁盘。在生产环境中使用此技术，你必须建立沙箱（Sandbox）。

• 代码审查：确保动态代码来源可信。
• 使用受限的AppDomain：在完整的.NET框架中，可以创建新的AppDomain并设置权限集（PermissionSet），限制代码的访问能力。但Unity（尤其是IL2CPP）对此支持有限。
• 解释执行而非编译：考虑使用Lua、JavaScript等脚本语言，它们有更成熟的沙箱环境。对于C#，可研究Roslyn脚本API或Mono.CSharp评估器，它们可能提供更多控制，但复杂度更高。
• 功能白名单：通过反射，在调用动态代码方法前，检查其是否只调用了允许的API。

5. 实战扩展：与Addressables资源系统集成

在实际项目中，动态代码通常作为可更新内容的一部分，与资源管理系统紧密集成。以下是和Unity Addressables系统集成的思路：

1. 打包：将C#脚本文件（.cs）或文本文件（.txt）标记为Addressables资源，并打包到远程或本地组。
2. 加载：使用Addressables的异步API加载文本资源。

   using UnityEngine.AddressableAssets; using UnityEngine.ResourceManagement.AsyncOperations; public static async UniTask<string> LoadSourceFromAddressablesAsync(string address) { var handle = Addressables.LoadAssetAsync<TextAsset>(address); TextAsset textAsset = await handle.ToUniTask(); // 注意：Addressables需要手动管理释放，这里简化为不释放，实际需根据生命周期管理 // Addressables.Release(handle); 应在合适时机调用 return textAsset.text; }

3. 依赖管理：如果动态代码依赖了项目中的其他DLL，这些DLL也需要作为Addressables资源打包，并在编译前，从加载的DLL资源中提取路径，添加到编译器参数中。这需要更复杂的资源管理和版本对应机制。

6. 性能实测与心得体会

在我自己的一个中型项目中进行实测，加载一个约200行的复杂逻辑类：

• 同步编译：在主线程直接编译，导致游戏卡顿约180-250毫秒，帧率骤降肉眼可见。
• 使用UniTask异步编译：编译工作被卸载到线程池，主线程仅在编译完成后的帧里进行实例化和接口调用，卡顿完全消失，编译期间的帧率保持稳定。

最重要的心得：

• 接口契约先行：在设计期就定义好清晰的接口，这是保证系统可维护性的关键。动态代码只应关注实现，而不是创造新的公共API。
• 生命周期管理：谁创建，谁负责。对于动态创建的对象和加载的Addressables资源，必须有清晰的释放机制，防止内存泄漏。可以使用CancellationTokenSource来统一取消异步操作。
• 拥抱HybridCLR：如果你的项目热更新需求强烈，且目标是IL2CPP，强烈建议直接使用HybridCLR。它是一个成熟、稳定、高性能的C#热更新方案，完美解决了IL2CPP下的动态代码加载问题，其原理是补充元数据而非动态编译，兼容性和性能都好得多。本指南的CodeDom方案更适合Mono后端、编辑器工具开发或原型验证。
• 日志与监控：为动态编译加载过程添加详细的日志，记录编译耗时、缓存命中率、加载来源等。这有助于线上问题的排查和性能优化。

动态代码加载是一把强大的双刃剑。它赋予了游戏前所未有的灵活性和可扩展性，但也带来了复杂性、安全风险和性能挑战。从一个小型编辑器工具开始尝试，理解其每一处细节，再谨慎地评估是否将其用于核心游戏逻辑，这才是稳健的技术演进之路。