三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

Unity代码裁剪深度解析：Managed Stripping Level机制与反射代码保留策略

发布时间：2026/8/10 23:23:41 三亩地 编程学习日记
Unity代码裁剪深度解析：Managed Stripping Level机制与反射代码保留策略

1. 项目概述：为什么我们需要关心Managed Stripping Level？

如果你在Unity项目里用过IL2CPP后端打包，肯定在Player Settings的Optimization部分见过这个选项：Managed Stripping Level。默认情况下，Unity会把它设为Low（对于IL2CPP）或Disabled（对于Mono）。很多开发者，尤其是刚接触Unity性能优化的朋友，看到“High”这个选项，第一反应可能是：“选High！肯定能减包，性能优化嘛，越高越好！” 然后兴冲冲地勾上，打包，测试，一切正常，发布。直到某一天，游戏在某个特定场景崩溃，或者某个反射调用的功能莫名其妙失效，你才会回过头来盯着这个选项，心里犯嘀咕：“它到底删了啥？”

这就是我们今天要深挖的坑。Managed Stripping Level，尤其是设为High时，是Unity构建过程中一个极其激进且“聪明”的代码裁剪工具。它的核心目标很简单：移除你的项目中所有“未被使用”的托管（C#）代码，从而减小最终构建包的大小，并可能缩短IL2CPP的代码生成时间。听起来很美，对吧？但问题就出在“未被使用”这个判定上。Unity的链接器（UnityLinker）进行的是静态代码分析，它无法预知运行时（Runtime）通过反射、动态加载、序列化等机制调用的代码。当你把级别调到High，链接器会采取最激进的策略，尽可能多地剔除它认为无用的代码，这时就极易误伤那些“静态分析不可见，但运行时至关重要”的部分。

我经历过不止一次因为设为High而导致线上事故的案例：一次是游戏内的配置表通过JsonUtility反序列化时，目标类因为构造函数未被显式调用而被整个剥离，导致反序列化失败，数据全空；另一次是使用了某个第三方插件，其内部通过Assembly.Load动态加载程序集，High级别下，那个程序集直接被排除在构建之外，功能完全失效。所以，理解“High到底删了啥”，不是为了炫技，而是为了在追求包体瘦身和确保功能稳定之间，找到那个安全的平衡点。

2. 核心机制解析：UnityLinker是如何工作的？

要弄明白High级别删了什么，首先得了解Unity的代码剥离（Stripping）是如何运作的。这个过程的核心执行者是一个叫做UnityLinker的工具，它是Mono项目中的IL Linker的一个定制版本。

2.1 静态分析与“根”标记

UnityLinker的工作流程可以概括为“标记与清除”。它不会运行你的游戏，而是像一位极其严格的图书管理员，只根据“借书卡”来判定哪些书（代码）有人看。

  1. 收集所有程序集：首先，它会收集你项目中所有可能被打包进去的托管程序集（DLL）。这包括：

    • 你的项目脚本编译成的程序集（如Assembly-CSharp.dll）。
    • 你导入的插件、第三方库的程序集。
    • .NET框架/类库中的核心程序集（如mscorlib.dll,System.dll）。
    • Unity引擎自身的托管程序集（如UnityEngine.Core.dll）。

  2. 标记“根”（Roots）：这是最关键的一步。链接器会从一些确定的“根”开始，标记所有它能找到的、被这些根直接或间接引用到的代码。这些“根”通常包括：

    • 场景中GameObject上挂载的MonoBehaviour脚本类。
    • 标记了[RuntimeInitializeOnLoadMethod]的方法（在游戏启动时自动执行）。
    • 项目中通过Resources.Load等方式静态引用的资源所关联的脚本。
    • 在link.xml文件中明确指定要保留的类型和成员。
    • 标记了[Preserve]属性的代码。
    • 对于Low级别，它还会保守地将所有公共类型和成员视为潜在的“根”。

  3. 依赖分析：从这些“根”出发，链接器会分析它们的依赖关系。例如，一个MonoBehaviour类A引用了类B，类B又调用了类C的某个方法。那么A、B、C以及它们用到的所有字段、属性、方法都会被标记为“已使用”。

  4. 清除未标记代码：所有在步骤2和3中未被标记的类、方法、属性、字段等，都会被认定为“死代码”（Dead Code），并在最终的构建中被移除。它们不会出现在最终的IL2CPP转换后的C++代码中，也不会存在于最终的二进制包里。

2.2 不同剥离级别的核心差异

Managed Stripping Level的三个选项（Low, Medium, High）本质上定义了链接器在第一步“标记根”时的激进程度。

  • Low (低)：安全优先。采用最保守的根标记规则。除了上述明确的根，它还会将所有公共类型和公共成员都视为潜在的根。这意味着，即使一个公共类在代码中没有任何地方被显式引用，只要它是public的，就不会被删除。这是IL2CPP后端的默认设置，旨在最大程度保证兼容性，避免误删。
  • Medium (中)：平衡模式。它不再自动将所有公共类型视为根。只有那些在场景、资源或通过其他方式被实际引用的类型才会被标记。这能移除更多未使用的公共库代码（比如.NET类库中你完全没用的部分），但风险也随之增加。如果你的代码通过反射调用了一个public但未被静态引用的方法，它就可能被删掉。
  • High (高)：激进瘦身。在Medium的基础上，进一步采取更激进的优化策略。它不仅采用最严格的根标记规则（只认最明确的根），还会对代码本身进行内联和裁剪等更底层的优化。例如，它会尝试将简单的属性访问器内联，删除空的try/finally块，甚至移除一些在目标平台上不被支持的功能模块（如Windows平台不支持的COM相关代码）。这是减包效果最明显，但也是风险最高的级别。

重要提示：Unity官方手册明确指出，当使用.NET 3.5 Scripting Runtime时，Medium和High级别是不可用的。只有升级到.NET 4.x或更新的Unity 2022+版本中默认的.NET Standard 2.1等，才能使用这些高级别剥离。

3. High级别下，哪些代码最容易被“误杀”？

了解了机制，我们就可以具体看看，当你心怀侥幸（或不知情）地选择了High时，UnityLinker那把锋利的“剪刀”最可能剪掉哪些看似无用、实则关键的代码。以下是我在实际项目中踩过或见过的典型“坑”。

3.1 反射（Reflection）调用的所有代码

这是头号重灾区。静态分析无法追踪运行时通过字符串名称动态调用的代码。

  • Type.GetType(“MyClass”)和Assembly.GetType(…)：如果你用字符串获取一个类型，而这个类型在代码中没有其他任何“静态”引用，它会被删除。
  • MethodInfo.Invoke、PropertyInfo.GetValue/SetValue、FieldInfo.GetValue/SetValue：通过反射调用的方法、属性、字段，如果其所属的类或成员本身没有被静态引用，会被删除。
  • Activator.CreateInstance(type)：动态创建的类实例，如果该类构造函数没有被静态调用过，类定义可能被移除。
  • 常见的应用场景：
    • 配置数据加载：使用JsonUtility.FromJson<T>或第三方JSON库（如Newtonsoft.Json）反序列化到一个类。如果这个类T只在反序列化的泛型参数中出现，而没有任何一个地方new T()或将其作为变量类型，High级别下这个类很可能被剥离。
    • 依赖注入框架：许多DI框架（如Zenject, VContainer）在启动时会扫描程序集，通过反射查找标记了特定属性（如[Inject]）的类并实例化它们。如果这些类没有被直接引用，会被删除。
    • 自定义编辑器工具：在Editor脚本中，经常使用反射来访问私有API或实现通用功能。这些代码在Runtime构建时可能被误删。

3.2 序列化与反序列化依赖的类

除了上述的JSON，还包括：

  • UnityEngine.JsonUtility：同上，严重依赖反射。
  • System.Xml.Serialization：XML序列化器在背后大量使用反射来构建序列化信息。
  • BinaryFormatter（虽然已不推荐使用）：同样依赖反射。
  • 自定义序列化：如果你实现了ISerializable接口，在GetObjectData方法中序列化的类型，如果未被静态引用，也可能被移除。

3.3 通过接口或基类动态绑定的代码

这有点微妙，但很常见。如果你的代码依赖接口或抽象类，而具体实现类只在配置文件中声明，或在运行时通过反射加载：

public interface IEnemyAI { void Think(); } public class AggressiveAI : IEnemyAI { public void Think() { /* ... */ } } public class DefensiveAI : IEnemyAI { public void Think() { /* ... */ } } // 在某个配置或资源中定义了要使用 “AggressiveAI” // 运行时通过反射创建：IEnemyAI ai = (IEnemyAI)Activator.CreateInstance(Type.GetType(aiTypeName));

在这个例子中，AggressiveAI和DefensiveAI都实现了IEnemyAI。但如果你的代码里没有任何一处直接new AggressiveAI()或new DefensiveAI()，High级别的链接器会认为这两个具体类从未被使用，从而将它们删除。即使IEnemyAI接口被多处使用也无济于事，因为链接器分析的是具体的类型依赖。

3.4 事件（Event）和委托（Delegate）

某些通过动态方式添加的事件处理器可能被影响。如果事件的添加操作是通过反射或字符串匹配完成的，那么处理事件的方法可能因为未被静态引用而被移除。

3.5 来自插件或第三方库的“隐藏”入口

许多第三方库（尤其是那些提供强大扩展性的库）有自己的初始化机制。它们可能：

  • 在某个静态构造函数或[RuntimeInitializeOnLoadMethod]中注册自己。
  • 通过查找程序集中所有继承自某个基类的类型来提供功能。 如果这个库的核心类没有被你的代码直接引用（比如你只是通过配置文件启用它），High级别可能会把这个库的核心逻辑代码都剪掉，导致功能完全失效。

3.6 .NET 外部程序集（Facade Assemblies）

这是High级别一个特殊的行为。.NET中有一些“外观”程序集，如netstandard.dll，它们只包含API定义，实际实现转发到其他程序集（如System.Runtime.dll）。在Low和Medium级别，为了安全，链接器会保留这些外观程序集。但在High级别，链接器会认为运行时不需要这些外观，从而将它们全部移除。如果你的代码中存在依赖这些外观程序集进行反射查找的情况，在High级别下可能会失败。

4. 防御策略：如何告诉UnityLinker“手下留情”？

知道了风险，我们不是要因噎废食，而是要学会安全地使用High级别来获得减包收益。Unity提供了几种机制来显式地告诉链接器：“这些代码很重要，请务必保留。”

4.1 使用[Preserve]属性

这是最直接、最细粒度的控制方式。你可以在你的类、方法、属性、字段上添加UnityEngine.Scripting.PreserveAttribute属性。

using UnityEngine.Scripting; [Preserve] // 保留整个类及其默认构造函数 public class MyConfigClass { public int id; public string name; [Preserve] // 特别保留此方法，即使它未被直接调用 public void MyDynamicMethod() { } } // 或者，如果你不想引入UnityEngine.Scripting命名空间，可以自定义属性 public class CustomPreserveAttribute : System.Attribute { } [CustomPreserve] public class AnotherClass { }

注意事项：

  • [Preserve]放在类上，会保留这个类以及它的默认构造函数。如果你需要保留带参数的构造函数或其他构造函数，必须单独标记。
  • [Preserve]放在程序集级别（[assembly: Preserve]）会保留该程序集中的所有类型，相当于给整个DLL上了保险。慎用，可能会显著增加包体。
  • UnityLinker能识别UnityEngine.Scripting.PreserveAttribute和你自定义的继承自System.Attribute的PreserveAttribute。

4.2 使用link.xml文件

这是更强大、更灵活的配置方式。你可以在项目的Assets文件夹（或其任何子目录）下创建一个名为link.xml的文件。UnityLinker在构建时会读取并遵循这个文件的指令。

<linker> <!-- 保留整个程序集 --> <assembly fullname="MyGame.Assembly1" preserve="all"/> <!-- 保留程序集，但不显式保留任何内容（通常用于强制链接器分析该程序集） --> <assembly fullname="MyGame.Assembly2" preserve="nothing"/> <!-- 保留特定程序集中的特定类型和成员 --> <assembly fullname="MyGame.Assembly3"> <!-- 保留整个类型 TypeA 及其所有成员 --> <type fullname="MyGame.Assembly3.TypeA" preserve="all"/> <!-- 保留类型 TypeB，但不指定成员，则默认保留所有成员 --> <type fullname="MyGame.Assembly3.TypeB" /> <!-- 只保留类型 TypeC 的所有字段 --> <type fullname="MyGame.Assembly3.TypeC" preserve="fields"/> <!-- 只保留类型 TypeD 的所有方法 --> <type fullname="MyGame.Assembly3.TypeD" preserve="methods"/> <!-- 只保留类型 TypeE 本身（不保留其成员） --> <type fullname="MyGame.Assembly3.TypeE" preserve="nothing"/> <!-- 保留类型 TypeF，并精确指定要保留的成员 --> <type fullname="MyGame.Assembly3.TypeF"> <field name="myField" /> <method signature="System.Void MyMethod(System.String)" /> <property name="MyProperty" /> </type> <!-- 使用通配符保留命名空间下所有类型 --> <type fullname="MyGame.Assembly3.SomeNamespace.*" /> <!-- 保留名称以“Helper”开头的所有类型 --> <type fullname="MyGame.Assembly3.Helper*" /> </assembly> <!-- 处理可能不存在的程序集（避免报错） --> <assembly fullname="OptionalAssembly" ignoreIfMissing="1"> <type fullname="OptionalAssembly.SomeType" /> </assembly> </linker>

link.xml的强大之处：

  • 精细控制：可以精确到具体的属性、方法、字段。
  • 条件保留：通过required="0"等属性，可以指定仅在类型被使用时才保留其成员。
  • 处理泛型：可以指定泛型类型和方法签名。
  • 通配符：支持使用*来匹配命名空间或类型名前缀。
  • 平台特定保留：使用feature属性可以指定只在特定平台保留代码（如feature="com"表示仅在支持COM的平台上保留）。

实操心得：对于大型项目或使用复杂第三方库时，维护一个全面的link.xml文件是更可靠的做法。你可以先从库的文档中查找是否有推荐的link.xml配置。很多优秀的插件（如一些IoC容器、序列化库）会在包中自带一个link.xml文件。

4.3 使用[RuntimeInitializeOnLoadMethod]属性

如果一个方法标记了[RuntimeInitializeOnLoadMethod]，它会在游戏加载时自动执行，因此链接器会将其视为一个明确的“根”，从而保留这个方法及其所属的类。你可以利用这一点来“激活”那些仅被反射使用的类。

using UnityEngine; public class ReflectionUsedClass { public void ImportantMethod() { } } public class Preserver { [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)] static void ForceLink() { // 这个方法本身什么都不用做，它的存在只是为了确保ReflectionUsedClass被链接器看到。 // 甚至可以加一个假的引用，但通常不需要。 // var dummy = typeof(ReflectionUsedClass); } }

这种方法相当于给链接器一个“提示”：Preserver.ForceLink方法在启动时会被调用，因此Preserver类会被保留。虽然它没有直接引用ReflectionUsedClass，但有时这种间接的“激活”能改变链接器的分析行为（尤其是在Medium级别下）。不过，在High级别下，这种方法可能不够直接，更推荐使用[Preserve]或link.xml。

4.4 策略选择与最佳实践

  1. 从Low开始，逐步提升：新项目或不确定时，始终使用Low级别。这是最安全的。
  2. 针对性测试：当你决定尝试Medium或High时，不要直接用于发布构建。先打一个开发包，进行全面的功能测试，特别是：
    • 所有通过资源（如ScriptableObject、Prefab）配置的功能。
    • 所有网络通信和数据反序列化环节。
    • 所有使用了反射或动态类型加载的模块（如插件系统、Mod支持）。
    • 运行所有单元测试和集成测试（如果项目有）。
  3. 利用构建报告：Unity构建完成后，会生成一个构建报告。查看其中的Stripping部分，可以看到被移除的程序集和大概的代码体积减少情况。这能帮你直观了解优化效果。
  4. 第三方库检查：查阅你使用的所有重要第三方插件的文档，看它们是否有关于代码剥离的特别说明或需要添加的link.xml配置。
  5. 建立保留清单：为你的项目维护一个link.xml文件，将已知的通过反射使用的类、序列化类、接口实现类等逐步添加进去。这是一个持续的过程。

5. 诊断与排查：当问题发生时，如何定位？

即使万分小心，问题可能还是会发生。游戏在编辑器里运行正常，但打出来的包某个功能崩溃了，日志显示MissingMethodException或TypeLoadException。如何快速定位是不是Managed Stripping惹的祸？

5.1 排查流程

  1. 确认剥离级别：首先检查出问题的构建使用的Managed Stripping Level。如果是Disabled或Low，问题可能不在这里。如果是Medium或High，嫌疑很大。
  2. 分析错误信息：错误信息通常会明确指出缺失的类型或方法名，例如Could not find type ‘MyGame.Config’或Method ‘MyClass.DynamicInit’ not found。这给了你明确的线索。
  3. 临时降级测试：将剥离级别暂时改回Low，重新打包测试。如果问题消失，那么几乎可以确定是代码剥离导致。
  4. 定位相关代码：根据错误信息中的类型/方法名，在项目中全局搜索，找到它的定义位置。思考它是如何被调用的：
    • 是直接被new出来的吗？
    • 是作为泛型参数吗？（如List<MyType>）
    • 是通过反射（Type.GetType,Invoke）调用的吗？
    • 是某个接口的实现，但只有接口被引用吗？
    • 是否存在于一个未被直接引用的程序集（DLL）中？
  5. 添加保留指令：根据上一步的分析，为出问题的类型或成员添加[Preserve]属性，或者将其添加到项目的link.xml文件中。
  6. 验证修复：重新以High级别打包，测试功能是否恢复。

5.2 使用UnityEngine.Debug进行运行时检查

你可以在代码中添加一些简单的调试逻辑，在开发版本中检查类型是否存在。

void Awake() { #if !UNITY_EDITOR // 只在非编辑器环境下检查 // 检查一个可能被剥离的类型 var type = Type.GetType("MyGame.PotentiallyStrippedClass, Assembly-CSharp"); if (type == null) { Debug.LogError("CRITICAL: MyGame.PotentiallyStrippedClass was stripped! Check Managed Stripping Level and link.xml."); } else { Debug.Log("Type is present: " + type.FullName); } #endif }

5.3 反编译查看最终程序集（高级）

对于极其棘手的问题，你可以尝试反编译构建后的程序集来确认代码是否被移除。这需要一些高级工具和技巧：

  1. 使用IL2CPP构建后，Unity会生成一个转换后的C++代码工程（在Temp/StagingArea/Il2Cpp等路径下）。但直接阅读C++代码很困难。
  2. 更实用的方法是，在构建时启用Development Build和Script Debugging，然后使用像ILSpy或dnSpy这样的.NET反编译工具，尝试打开构建输出中的托管程序集（如global-metadata.dat文件无法直接反编译，但某些工具可以处理）。如果发现某个类或方法在反编译结果中完全消失，那就是被剥离了。

6. 高级技巧与特定场景处理

6.1 处理泛型序列化

泛型结合序列化是另一个容易出问题的点。考虑以下代码：

public class DataContainer<T> where T : new() { public T data; public void LoadFromJson(string json) { data = JsonUtility.FromJson<T>(json); // 问题点！ } } // 用法 public class PlayerConfig { /* ... */ } var container = new DataContainer<PlayerConfig>(); container.LoadFromJson(jsonString);

这里，PlayerConfig类型只作为泛型参数T出现。在High剥离级别下，PlayerConfig类可能因为没有被“直接”引用而被移除。解决方法是为PlayerConfig类添加[Preserve]属性，或者在link.xml中保留它。

6.2 处理来自程序集定义（Assembly Definition）的代码

如果你的项目使用了Assembly Definition文件来组织代码模块，需要确保包含反射调用目标的程序集被正确引用。链接器只会处理被打包进最终构建的程序集。如果反射加载的类在一个未被任何“根”直接或间接引用的程序集中，该整个程序集都可能不会被包含在构建中。你需要确保在Player Settings的Scripting Define Symbols或通过其他方式，让主程序集或一个肯定会被包含的程序集引用到它。

6.3 Unity版本差异

不同Unity版本的UnityLinker行为可能有细微差别。例如，对[Preserve]属性的支持程度、link.xml中feature属性的可用性等。在升级Unity版本后，如果出现新的剥离相关问题，需要查阅对应版本的官方手册。文中引用的Unity 2021.1手册内容是一个很好的基准，但2022.3或2023.3等新版本可能有优化或变更。

6.4 与IL2CPP编译器优化的交互

Managed Stripping发生在IL2CPP转换之前。被剥离的代码不会进入IL2CPP的转换流程。此外，IL2CPP自身也有代码优化选项（如Enable Engine Code Stripping）。它们协同工作，但管理的是不同层面：Managed Stripping处理C#/.NET字节码，IL2CPP优化处理生成的C++代码。通常，两者都开启能获得最小的包体，但风险也叠加。如果遇到极其诡异的问题，可以尝试单独关闭其中一个来排查。

7. 总结与最终建议

把Managed Stripping Level设为High，就像给项目进行一次激进的“代码减肥手术”。它能显著切除冗余的.NET框架代码和未使用的第三方库部分，对减少包体大小（特别是对于IL2CPP构建）有立竿见影的效果。然而，这场手术的风险在于，医生（UnityLinker）的判断完全基于静态的“解剖图”（你的代码结构），无法预知运行时复杂的“生理活动”（反射、动态加载等）。

我的个人实践建议是：

  1. 默认使用Low：对于大多数项目，特别是处于快速开发迭代期、大量使用第三方插件和反射技术的项目，Low级别提供了最佳的安全性和开发体验。减包收益的优先级应低于稳定性。
  2. 在项目稳定期尝试Medium：当核心功能稳定，并且你对自己的代码和使用的库有深入了解后，可以尝试切换到Medium级别。进行全面的回归测试，并准备好一个link.xml文件来应对出现的问题。
  3. 谨慎评估High：仅在你对项目的所有代码路径（包括反射和动态加载）有绝对掌控，并且包体大小是首要KPI时，才考虑使用High级别。这通常适用于发布前的最终优化阶段，并且需要伴随极其严格的测试流程。
  4. 将link.xml纳入版本管理：一旦你开始使用Medium或High级别，link.xml文件就成为项目构建的关键配置。务必将其加入版本控制系统（如Git），并随着代码的增删及时更新维护。
  5. 建立构建检查清单：在团队的构建发布流程中，加入对剥离相关错误的检查项。例如，在打出候选发布包后，专门运行一遍涉及数据加载、插件初始化的测试用例。

理解并善用Managed Stripping，是Unity开发者从初级走向中高级的必经之路。它不再是一个黑盒魔法，而是一个可以精细调控的工具。希望这篇指南能帮你避开这个“性能优化”路上的大坑，更自信、更安全地优化你的项目。

编程学习 学习日记 实战经验
← 返回列表