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的工作流程可以概括为“标记与清除”。它不会运行你的游戏而是像一位极其严格的图书管理员只根据“借书卡”来判定哪些书代码有人看。收集所有程序集首先它会收集你项目中所有可能被打包进去的托管程序集DLL。这包括你的项目脚本编译成的程序集如Assembly-CSharp.dll。你导入的插件、第三方库的程序集。.NET框架/类库中的核心程序集如mscorlib.dll,System.dll。Unity引擎自身的托管程序集如UnityEngine.Core.dll。标记“根”Roots这是最关键的一步。链接器会从一些确定的“根”开始标记所有它能找到的、被这些根直接或间接引用到的代码。这些“根”通常包括场景中GameObject上挂载的MonoBehaviour脚本类。标记了[RuntimeInitializeOnLoadMethod]的方法在游戏启动时自动执行。项目中通过Resources.Load等方式静态引用的资源所关联的脚本。在link.xml文件中明确指定要保留的类型和成员。标记了[Preserve]属性的代码。对于Low级别它还会保守地将所有公共类型和成员视为潜在的“根”。依赖分析从这些“根”出发链接器会分析它们的依赖关系。例如一个MonoBehaviour类A引用了类B类B又调用了类C的某个方法。那么A、B、C以及它们用到的所有字段、属性、方法都会被标记为“已使用”。清除未标记代码所有在步骤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.FromJsonT或第三方JSON库如Newtonsoft.Json反序列化到一个类。如果这个类T只在反序列化的泛型参数中出现而没有任何一个地方new T()或将其作为变量类型High级别下这个类很可能被剥离。依赖注入框架许多DI框架如Zenject, VContainer在启动时会扫描程序集通过反射查找标记了特定属性如[Inject]的类并实例化它们。如果这些类没有被直接引用会被删除。自定义编辑器工具在Editor脚本中经常使用反射来访问私有API或实现通用功能。这些代码在Runtime构建时可能被误删。3.2 序列化与反序列化依赖的类除了上述的JSON还包括UnityEngine.JsonUtility同上严重依赖反射。System.Xml.SerializationXML序列化器在背后大量使用反射来构建序列化信息。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 fullnameMyGame.Assembly1 preserveall/ !-- 保留程序集但不显式保留任何内容通常用于强制链接器分析该程序集 -- assembly fullnameMyGame.Assembly2 preservenothing/ !-- 保留特定程序集中的特定类型和成员 -- assembly fullnameMyGame.Assembly3 !-- 保留整个类型 TypeA 及其所有成员 -- type fullnameMyGame.Assembly3.TypeA preserveall/ !-- 保留类型 TypeB但不指定成员则默认保留所有成员 -- type fullnameMyGame.Assembly3.TypeB / !-- 只保留类型 TypeC 的所有字段 -- type fullnameMyGame.Assembly3.TypeC preservefields/ !-- 只保留类型 TypeD 的所有方法 -- type fullnameMyGame.Assembly3.TypeD preservemethods/ !-- 只保留类型 TypeE 本身不保留其成员 -- type fullnameMyGame.Assembly3.TypeE preservenothing/ !-- 保留类型 TypeF并精确指定要保留的成员 -- type fullnameMyGame.Assembly3.TypeF field namemyField / method signatureSystem.Void MyMethod(System.String) / property nameMyProperty / /type !-- 使用通配符保留命名空间下所有类型 -- type fullnameMyGame.Assembly3.SomeNamespace.* / !-- 保留名称以“Helper”开头的所有类型 -- type fullnameMyGame.Assembly3.Helper* / /assembly !-- 处理可能不存在的程序集避免报错 -- assembly fullnameOptionalAssembly ignoreIfMissing1 type fullnameOptionalAssembly.SomeType / /assembly /linkerlink.xml的强大之处精细控制可以精确到具体的属性、方法、字段。条件保留通过required0等属性可以指定仅在类型被使用时才保留其成员。处理泛型可以指定泛型类型和方法签名。通配符支持使用*来匹配命名空间或类型名前缀。平台特定保留使用feature属性可以指定只在特定平台保留代码如featurecom表示仅在支持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 策略选择与最佳实践从Low开始逐步提升新项目或不确定时始终使用Low级别。这是最安全的。针对性测试当你决定尝试Medium或High时不要直接用于发布构建。先打一个开发包进行全面的功能测试特别是所有通过资源如ScriptableObject、Prefab配置的功能。所有网络通信和数据反序列化环节。所有使用了反射或动态类型加载的模块如插件系统、Mod支持。运行所有单元测试和集成测试如果项目有。利用构建报告Unity构建完成后会生成一个构建报告。查看其中的Stripping部分可以看到被移除的程序集和大概的代码体积减少情况。这能帮你直观了解优化效果。第三方库检查查阅你使用的所有重要第三方插件的文档看它们是否有关于代码剥离的特别说明或需要添加的link.xml配置。建立保留清单为你的项目维护一个link.xml文件将已知的通过反射使用的类、序列化类、接口实现类等逐步添加进去。这是一个持续的过程。5. 诊断与排查当问题发生时如何定位即使万分小心问题可能还是会发生。游戏在编辑器里运行正常但打出来的包某个功能崩溃了日志显示MissingMethodException或TypeLoadException。如何快速定位是不是Managed Stripping惹的祸5.1 排查流程确认剥离级别首先检查出问题的构建使用的Managed Stripping Level。如果是Disabled或Low问题可能不在这里。如果是Medium或High嫌疑很大。分析错误信息错误信息通常会明确指出缺失的类型或方法名例如Could not find type ‘MyGame.Config’或Method ‘MyClass.DynamicInit’ not found。这给了你明确的线索。临时降级测试将剥离级别暂时改回Low重新打包测试。如果问题消失那么几乎可以确定是代码剥离导致。定位相关代码根据错误信息中的类型/方法名在项目中全局搜索找到它的定义位置。思考它是如何被调用的是直接被new出来的吗是作为泛型参数吗如ListMyType是通过反射Type.GetType,Invoke调用的吗是某个接口的实现但只有接口被引用吗是否存在于一个未被直接引用的程序集DLL中添加保留指令根据上一步的分析为出问题的类型或成员添加[Preserve]属性或者将其添加到项目的link.xml文件中。验证修复重新以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 反编译查看最终程序集高级对于极其棘手的问题你可以尝试反编译构建后的程序集来确认代码是否被移除。这需要一些高级工具和技巧使用IL2CPP构建后Unity会生成一个转换后的C代码工程在Temp/StagingArea/Il2Cpp等路径下。但直接阅读C代码很困难。更实用的方法是在构建时启用Development Build和Script Debugging然后使用像ILSpy或dnSpy这样的.NET反编译工具尝试打开构建输出中的托管程序集如global-metadata.dat文件无法直接反编译但某些工具可以处理。如果发现某个类或方法在反编译结果中完全消失那就是被剥离了。6. 高级技巧与特定场景处理6.1 处理泛型序列化泛型结合序列化是另一个容易出问题的点。考虑以下代码public class DataContainerT where T : new() { public T data; public void LoadFromJson(string json) { data JsonUtility.FromJsonT(json); // 问题点 } } // 用法 public class PlayerConfig { /* ... */ } var container new DataContainerPlayerConfig(); 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的判断完全基于静态的“解剖图”你的代码结构无法预知运行时复杂的“生理活动”反射、动态加载等。我的个人实践建议是默认使用Low对于大多数项目特别是处于快速开发迭代期、大量使用第三方插件和反射技术的项目Low级别提供了最佳的安全性和开发体验。减包收益的优先级应低于稳定性。在项目稳定期尝试Medium当核心功能稳定并且你对自己的代码和使用的库有深入了解后可以尝试切换到Medium级别。进行全面的回归测试并准备好一个link.xml文件来应对出现的问题。谨慎评估High仅在你对项目的所有代码路径包括反射和动态加载有绝对掌控并且包体大小是首要KPI时才考虑使用High级别。这通常适用于发布前的最终优化阶段并且需要伴随极其严格的测试流程。将link.xml纳入版本管理一旦你开始使用Medium或High级别link.xml文件就成为项目构建的关键配置。务必将其加入版本控制系统如Git并随着代码的增删及时更新维护。建立构建检查清单在团队的构建发布流程中加入对剥离相关错误的检查项。例如在打出候选发布包后专门运行一遍涉及数据加载、插件初始化的测试用例。理解并善用Managed Stripping是Unity开发者从初级走向中高级的必经之路。它不再是一个黑盒魔法而是一个可以精细调控的工具。希望这篇指南能帮你避开这个“性能优化”路上的大坑更自信、更安全地优化你的项目。