1. 项目概述Managed Stripping Level 的“双刃剑”在 Unity 项目开发的最后冲刺阶段打包优化是每个开发者绕不开的坎。Player Settings 里那个不起眼的 “Managed Stripping Level” 选项尤其是当它被设置为 “High” 时常常是项目包体“瘦身”的功臣但也可能是导致线上崩溃、功能缺失的“隐形杀手”。我见过太多团队在临近上线时为了追求极致的包体大小毫不犹豫地将这个选项调到 High结果在真机测试或上线后发现一些通过反射、动态加载或特定序列化方式调用的代码神秘消失了游戏逻辑出现诡异错误排查起来如同大海捞针。这个选项的本质是 Unity 构建管线中的一个关键优化步骤由 UnityLinker基于 Mono IL Linker工具执行。它的工作逻辑很直接通过静态代码分析找出那些在运行时永远不可能被访问到的托管代码C# 字节码并将其从最终的构建包中剔除。这听起来很美但问题在于静态分析无法完全预测动态行为。当你选择 “High” 级别时UnityLinker 会采取最激进的策略以牺牲一定的代码安全性为代价追求最小的代码体积。它不再像 “Low” 或 “Medium” 级别那样保守会移除大量它认为“无用”的代码包括一些通过非直接调用路径如反射、接口回调、特定事件系统触发的逻辑。简单来说“High” 级别删掉的是 UnityLinker 在静态分析阶段无法证明会被用到的任何托管代码。这不仅仅是你的业务代码还包括引用的第三方程序集DLL、甚至 .NET Framework/Standard 库中的部分。对于追求极致包体大小的移动端、WebGL 或小游戏平台项目这个选项诱惑巨大但随之而来的风险也需要我们透彻理解并谨慎应对。2. 核心机制UnityLinker 如何决定“删”与“留”要避坑首先得明白坑是怎么挖的。UnityLinker 的工作流程可以概括为“标记与清扫”。2.1 工作流程解析UnityLinker 的处理并非在编译时而是在所有 C# 代码编译成 IL中间语言之后生成最终可执行文件之前。它接收的是你项目中所有程序集你的代码、插件 DLL、.NET 库的 IL 代码副本。其工作分为两大阶段根标记 (Root Marking)这是决定代码去留的第一步。UnityLinker 会从一组确定的“根”类型和成员开始扫描。这些“根”是它认为程序运行时一定会被访问到的入口点。常见的根包括场景中 GameObject 上挂载的MonoBehaviour派生类的实例。标记了[RuntimeInitializeOnLoadMethod]的方法。通过link.xml文件或[Preserve]属性显式声明要保留的类型和成员。在 “Low” 剥离级别下所有公共类型和成员也可能被标记为根为了安全。依赖分析与剪枝 (Dependency Analysis Pruning)从这些“根”出发UnityLinker 会递归地分析所有被直接或间接引用到的类型、方法、属性、字段等。凡是在这个依赖关系图中能被访问到的节点都会被标记为“需要保留”。在此过程结束后所有未被标记的 IL 代码无论它原本属于哪个类库都会被无情地移除。最终只有被标记的代码会进入构建包。2.2 不同剥离级别的策略差异“Managed Stripping Level” 的三个选项本质上控制的是“根标记”阶段的激进程度。剥离级别核心策略包体大小风险程度适用场景Disabled不进行任何托管代码剥离。所有代码包括未使用的 .NET 库部分都会包含在包内。最大零风险但IL2CPP后端不可用此选项Mono 脚本后端下的快速原型、调试。Low安全性优先。采用保守的根标记规则。除了明显的根还会保留所有公共类型和成员以防动态调用。对第三方库和 .NET 外部引用程序集也尽量保留。较大极低绝大多数项目的安全选择尤其是使用了反射、动态加载或不确定依赖关系的项目。IL2CPP 的默认选项。Medium平衡策略。在 Low 和 High 之间取得平衡。不再自动保留所有公共成员但对项目程序集内的代码仍相对保守。中等中等对包体大小有要求且代码结构相对清晰、动态特性使用较少的项目。High体积优先。采用最激进的根标记规则。只保留它能明确证明会被用到的代码。对 .NET 外部引用程序集如netstandard.dll也会进行剥离。甚至会对方法体进行内联和裁剪等优化。最小高对包体大小极度敏感的发布版本如超休闲手游、WebGL且团队对代码的静态调用链路有绝对把握并做好了完备的保留配置。关键提示“High” 级别下UnityLinker 会执行额外的代码转换优化例如将简单的属性访问器getter/setter内联甚至移除空的try/finally块。这些优化在进一步减小体积的同时也可能微妙地改变堆栈跟踪信息给调试带来额外困难。2.3 “High” 级别下被重点审查的代码在 “High” 级别下以下类型的代码是“高危”删除对象通过反射调用的所有内容Type.GetType(“MyClass”),Assembly.GetExecutingAssembly().GetTypes(),MethodInfo.Invoke()。UnityLinker 的静态分析无法追踪这些动态决议。未被直接引用的序列化/反序列化类如果你使用JsonUtility,Newtonsoft.Json或自定义二进制序列化那些只作为数据载体、从未在代码中被new或作为参数类型显式使用的类可能会被删除。接口实现类仅通过接口类型引用的具体实现类如果该接口引用在分析时被认为是“死的”例如通过一个从未被调用的工厂方法返回那么实现类可能被删。事件系统的监听器通过操作符添加的事件处理程序通常能被分析到但如果监听器是通过字符串名称、反射或复杂的委托链添加的则可能丢失。来自第三方插件尤其是通过 DLL 引入的“隐藏”入口点某些插件可能通过读取配置文件、使用[RuntimeInitializeOnLoadMethod]在非显眼处初始化这些入口点如果未被正确识别其相关代码会被整体移除。.NET 标准库中的“外部”引用程序集在 “High” 级别下像netstandard.dll这样的外部引用程序集本身也会被分析并剥离未使用的部分这有时会意外移除一些被间接依赖的 API。3. 实战配置与保留关键代码理解了风险我们就可以有针对性地进行防御。核心思想是告诉 UnityLinker“这些代码虽然你看不出来怎么用但我保证运行时一定会用到请务必保留”。3.1 第一道防线使用[Preserve]属性这是最直接、最代码化的方式。你可以在你认为关键的类、方法、属性或字段上添加UnityEngine.Scripting.PreserveAttribute属性。using UnityEngine.Scripting; // 保留整个类及其默认构造函数 [Preserve] public class MyDataModel { // 这个字段可能被序列化使用 public int id; // 这个方法可能通过反射调用 [Preserve] public void InitializeFromConfig(string config) { ... } } // 保留一个可能通过接口工厂创建的类 [Preserve] public class ConcreteService : IService { ... }注意事项[Preserve]标记一个类时会同时保留其默认构造函数。如果你只想保留类本身但不保留其默认构造则需要使用link.xml进行更精细的控制。这个属性可以应用于程序集级别[assembly: Preserve]。这会将整个程序集内的所有类型都标记为需要保留非常强力但可能过度保留代码。慎用。对于第三方库的代码你无法直接修改源码添加[Preserve]。这时就需要用到link.xml。3.2 第二道防线创建link.xml文件link.xml是一个基于项目的配置文件它允许你以声明的方式告诉 UnityLinker 保留什么。在项目Assets文件夹或其任何子目录下创建一个名为link.xml的文件即可。linker !-- 保留整个程序集 ‘MyCompany.MyGame’ -- assembly fullnameMyCompany.MyGame preserveall/ !-- 保留特定程序集中的特定类型及其所有成员 -- assembly fullnameThirdPartyPlugin type fullnameThirdPartyPlugin.ConfigManager preserveall/ /assembly !-- 更精细的控制只保留某个类的特定方法和属性 -- assembly fullnameMyCompany.MyGame type fullnameMyCompany.MyGame.Serializer !-- 通过签名保留方法 -- method signatureSystem.String SerializeObject(System.Object) / !-- 通过名称保留属性存在重载时可能不精确建议用签名 -- property nameDefaultEncoding / /type !-- 使用通配符保留某个命名空间下的所有类型 -- type fullnameMyCompany.MyGame.DataModels.* / /assembly !-- 处理泛型类型 -- assembly fullnameMyCompany.MyGame type fullnameMyCompany.MyGame.GenericFactory1 method signatureSystem.Object CreateInstancelt;Tgt;(System.String) / /type /assembly !-- 强制处理一个程序集即使它未被直接引用但不显式保留任何内容。 适用于通过反射动态加载的程序集 -- assembly fullnameOptionalPlugin preservenothing / /linkerlink.xml使用心得程序集全名fullname需要程序集的完整名称包括版本、文化、公钥令牌等。通常你可以先不写这些只写简单名称如Assembly-CSharp如果无效再尝试从构建日志或Temp/StagingArea目录下的 DLL 文件中获取完整名称。preserve属性在type节点上preserveall保留类型及其所有成员preservefields只保留字段preservenothing仅保留类型元数据用于反射不保留成员。不指定preserve且未列出成员则默认保留所有成员。通配符*在类型全名的末尾可用于匹配命名空间下所有类型或具有相同前缀的类型。处理“缺失”程序集如果你的link.xml可能引用一个在某些平台构建时不存在的程序集可以添加ignoreIfMissing1属性到assembly节点避免链接器报错。3.3 第三道防线[RuntimeInitializeOnLoadMethod]与AlwaysLinkAssembly对于某些插件或模块其入口点是一个在运行时自动执行的方法。确保这个方法不被剥离就能保住它所在的整个调用链。using UnityEngine; public class PluginBootstrapper { // 这个方法会在运行时初始化时自动调用因此它会被标记为根。 // 只要这个方法不被剥离它内部调用的所有类型和方法通常也能被保留。 [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)] private static void OnRuntimeInitialize() { // 初始化插件这里可能会调用一些容易被剥离的代码。 ThirdPartyPlugin.Core.Initialize(); } }更进一步如果一个程序集完全通过反射或资源加载在代码中没有直接引用你可以使用[assembly: UnityEngine.Scripting.AlwaysLinkAssembly]属性。将它放在该程序集的任何 C# 文件中通常在AssemblyInfo.cs中可以强制 UnityLinker 对该程序集应用根标记规则。注意这并不直接保留程序集内的代码只是让它进入链接器的分析流程。如果分析后仍找不到任何根它还是会被移除。3.4 诊断与验证如何知道什么被删了在踩坑之前最好能先看看坑在哪。Unity 提供了构建后分析托管代码剥离结果的方法。构建日志在 Unity Console 窗口构建完成后搜索输出日志中的UnityLinker相关条目。它会列出处理了哪些程序集。但信息比较概括。使用link.xml生成报告在link.xml中你可以要求 UnityLinker 输出一个依赖关系报告。这需要在命令行构建时传递特定参数或者通过一些编辑器脚本调用构建管线 API 来实现过程稍复杂但能生成详细的 HTML 报告展示每个程序集、类型、成员的保留/移除状态。最实用的方法对比构建。首先用Stripping Level Low或Disabled打一个包。然后用Stripping Level High打一个包。解压两个包APK/IPA 是压缩包可以解压找到其中的托管程序集如Assembly-CSharp.dll。使用像ILSpy或dnSpy这样的 .NET 反编译工具分别打开两个版本的程序集直观地对比哪些命名空间、类、方法在High模式下消失了。这是定位问题最直接的方式。4. 常见问题排查与修复实录在实际项目中切换到 “High” 剥离级别后你可能会遇到以下典型问题。这里记录了我踩过的坑和解决方案。4.1 问题反序列化时抛出JsonException: Cannot deserialize the current JSON object...场景游戏使用 JSON 保存存档。在编辑器和平板测试Low/Medium 级别下一切正常切换到 High 级别打包后加载存档时报错提示无法反序列化到某个类型。根因分析你的存档数据中包含一个PlayerInventory类。在代码中你可能通过一个InventoryManager的静态属性来访问它而序列化/反序列化是通过JsonUtility.FromJsonPlayerInventory(json)进行的。UnityLinker 在静态分析时如果找不到任何直接new PlayerInventory()或者InventoryManager.CurrentInventory假设其类型是PlayerInventory的引用它就可能认为PlayerInventory类未被使用从而将其从程序集中移除。当反序列化试图实例化这个不存在的类时自然失败。解决方案为数据类添加[Preserve]属性这是最推荐的做法。[System.Serializable] [UnityEngine.Scripting.Preserve] // 添加这一行 public class PlayerInventory { public ListItem items; }在link.xml中保留linker assembly fullnameAssembly-CSharp type fullnameMyGame.PlayerInventory preserveall/ /assembly /linker确保有一个静态引用在游戏启动的某个地方显式地声明一个该类型的变量或进行一次无用的实例化不优雅但有效。// 在某个一定会执行的初始化方法中 void ForceReference() { // 这行代码的唯一目的就是让链接器看到这个类型被使用了 var dummy new PlayerInventory(); }4.2 问题第三方插件功能失效无任何错误日志场景导入了一个 UI 动画插件。在编辑器中运行完美但 High 级别打包后所有该插件提供的动画组件都不起作用控制台也没有错误。根因分析许多插件使用“约定优于配置”的模式。它们可能要求你在某个文件夹下放置一个配置文件或者通过反射扫描所有带有特定属性如[MyPluginAttribute]的类。在 High 剥离级别下插件用于扫描和注册这些类的“启动器”代码可能因为未被直接调用而被移除或者被扫描的类本身被移除了。解决方案查阅插件文档好的插件文档会明确说明是否需要为代码剥离进行特殊配置。寻找关于 “Code Stripping”、“Linker”、“IL2CPP” 或 “AOT” 的章节。检查插件提供的link.xml许多插件会在其Plugins文件夹内自带一个link.xml文件。确保它被正确包含在你的项目中。有时你需要手动将插件提供的示例link.xml内容合并到你自己的主link.xml中。寻找初始化方法在插件的脚本中寻找标记了[RuntimeInitializeOnLoadMethod]、[InitializeOnLoadMethod]或类似静态构造函数的方法。如果找到确保这个方法所在的类没有被剥离。你可以尝试在该类上添加[Preserve]。联系插件开发者如果以上都不行这可能是插件的一个已知问题。向开发者反馈他们可能需要更新插件以更好地支持代码剥离。4.3 问题使用Type.GetType(“MyNamespace.MyClass”)返回null场景你有一个模块化的设计通过字符串动态加载类型。在 High 剥离级别下Type.GetType调用返回null。根因分析Type.GetType使用字符串查找类型。如果该类型所在的程序集已被完全剥离因为链接器认为它未被引用或者该类型本身被移除那么查找就会失败。此外即使类型被保留如果其所在的命名空间程序集名称不匹配GetType也可能失败。GetType默认只在调用者所在程序集和 mscorlib 中查找对于其他程序集需要程序集限定名称。解决方案使用程序集限定名称Type.GetType(“MyNamespace.MyClass, MyAssembly”)。确保类型被保留使用[Preserve]或link.xml确保目标类型不会被移除。使用Assembly.GetType替代如果你知道类型所在的程序集可以先获取程序集再从中获取类型这样更可靠。var assembly Assembly.Load(“MyAssembly”); var type assembly.GetType(“MyNamespace.MyClass”);考虑使用更安全的类型管理机制例如使用一个中央注册表将字符串映射到System.Type引用或工厂委托而不是完全依赖运行时字符串查找。4.4 问题升级 Unity 版本或 .NET Standard 后出现MissingMethodException或TypeLoadException场景项目正常运行在升级 Unity 或切换 Scripting Runtime Version如从 .NET 3.5 到 .NET Standard 2.1后使用 High 剥离级别打包出现运行时异常。根因分析不同版本的 .NET 配置文件或 Unity 的底层库其程序集结构和内部依赖可能发生变化。High 剥离级别下链接器可能会更激进地移除它认为在新环境下“无用”的 .NET 标准库中的类型或方法而这些类型或方法可能被你的代码或第三方插件以某种隐蔽的方式依赖着。解决方案暂时调低剥离级别首先切回Medium或Low级别打包测试如果问题消失则确认是剥离引发的问题。审查和更新link.xml旧的link.xml配置可能针对旧的库版本需要更新。关注那些引用了特定 .NET 程序集如System,System.Core,netstandard的保留规则。检查第三方插件兼容性确保所有插件都支持你新升级的 Unity 版本和 .NET 配置。逐步排查这是一个比较棘手的问题。可以尝试创建一个最简项目只包含引发错误的代码和必要的依赖然后逐步添加link.xml保留规则直到问题解决。将有效的规则合并回主项目。5. 构建流程与最佳实践将 Managed Stripping Level 设置为 High 不应是临时的、冒险的决定而应该是一个经过验证的、稳定的构建流程的一部分。5.1 建立安全的打包检查清单在团队中建议建立如下流程开发期始终使用Low或Medium级别。这能最大化开发效率避免因代码剥离导致的奇怪编译或运行时错误干扰调试。每日构建/测试构建可以开始使用High级别但必须配合一套完整的、针对核心功能的自动化测试单元测试、集成测试。任何测试失败都应立即调查是否与代码剥离有关。发布候选构建在High级别下打包后除了自动化测试必须进行全面的手动测试特别是存档/读档功能。所有涉及动态内容加载资源、配置、代码的功能。所有第三方插件提供的功能。异常处理流程确保错误信息还能正常显示。保留link.xml作为版本控制文件将项目的link.xml文件纳入源码管理如 Git。每次添加新的需要动态加载或反射使用的类、或者引入新插件时都应评估是否需要更新此文件。5.2 针对不同平台的策略微调PC/主机平台包体大小限制相对宽松可以优先考虑稳定性。除非包体真的巨大否则使用Medium级别通常是安全且收益不错的选择。移动端 (iOS/Android)对包体大小敏感High级别收益显著。必须严格执行上述检查清单。特别注意 iOS 的 IL2CPP 后端它对代码剥离更敏感因为 AOT 编译需要所有类型信息。WebGLHigh级别几乎是必选项因为下载大小直接影响用户体验。WebGL 的初始化时间也受代码量影响。但 WebGL 的调试极其困难因此link.xml的配置必须格外小心和完备。小游戏平台与 WebGL 类似包体有严格限制。需要极致优化High级别配合精细的link.xml是标配。5.3 一个实用的增量配置方法不要试图一次性写出完美的link.xml。采用增量方式初始link.xml可以为空。将剥离级别设为High进行构建和基础测试。遇到一个运行时错误就通过反编译对比或分析找到缺失的类型/方法。将该类型/方法添加到link.xml中。重复步骤 2-4。随着时间的推移你的link.xml就会成为一个针对你项目特定模式常用的序列化类、反射模式、插件的、高度优化的保留配置。这个文件本身就成为了项目资产的一部分记录了哪些代码是动态依赖的。最后记住一个核心原则“High” 剥离级别是一种优化而所有优化都应在功能正确的前提下进行。不要为了追求几兆的体积缩减而引入难以预料的线上风险。花时间建立可靠的配置和测试流程才能让这个强大的工具真正为你所用而不是被它绊倒。在我经历的项目中那些成功稳定使用High级别的团队无一例外都拥有严谨的配置管理和测试文化。