Puerts Unity项目中PathHelper类被代码剥离的问题分析与解决

在Unity游戏开发中，使用Puerts进行TypeScript/JavaScript与C#交互时，开发者可能会遇到一个常见问题：当将Managed Stripping Level设置为High时，Puerts的PathHelper类及其方法会被Unity的代码剥离机制错误地移除，导致WebGL平台运行时出现"CS.Puerts.PathHelper.IsRelative is not a function"等错误。

问题背景

Puerts是一个连接TypeScript/JavaScript与Unity C#的桥梁，PathHelper类提供了一些路径处理的实用方法。在WebGL平台下，Puerts的运行时JavaScript代码(puerts-runtime.js)会调用这些C#方法。然而，Unity的代码剥离机制在优化时会移除看似未被使用的代码，而由于这些方法是通过反射调用的，静态分析无法识别它们的实际使用情况。

问题表现

当项目构建为WebGL且启用高级代码剥离时，控制台会抛出类似以下的错误：

Exception: TypeError: CS.Puerts.PathHelper.IsRelative is not a function

这表明PathHelper类的方法已被错误地从最终构建中移除，而运行时JavaScript代码却尝试调用这些方法。

解决方案

解决此问题的标准方法是为PathHelper类添加UnityEngine.Scripting.Preserve特性。这个特性会明确告诉Unity的代码剥离系统：即使表面上看起来没有引用，这些代码也必须保留。

具体实现方式是在PathHelper类定义前添加[Preserve]特性：

[UnityEngine.Scripting.Preserve]
public static class PathHelper
{
    // 类实现...
}

技术原理

Unity的Managed Stripping机制通过静态分析来确定哪些代码可以被安全移除。对于通过反射调用的方法，这种分析往往失效。[Preserve]特性的作用就是标记这些"隐形"被使用的代码，防止它们被错误剥离。

在Puerts的上下文中，JavaScript代码通过反射机制调用C#方法是一种常见模式，因此所有可能被JavaScript调用的C#类和方法都应该考虑添加Preserve特性。

最佳实践

1. 对于Puerts项目中所有可能被JavaScript调用的C#类，都应添加[Preserve]特性
2. 在WebGL平台构建前，建议将Managed Stripping Level设置为Low或Medium进行测试
3. 对于关键功能类，可以考虑创建link.xml文件来确保它们不会被剥离

总结

代码剥离是Unity优化包体大小的有效手段，但对于依赖反射的框架如Puerts，需要特别注意保留必要的类型和方法。通过合理使用[Preserve]特性，可以平衡代码优化与功能完整性的需求，确保项目在各平台都能稳定运行。