Tencent/puerts项目常见问题解答与解决方案

Tencent/puerts项目常见问题解答与解决方案

前言

Tencent/puerts是一个将TypeScript/JavaScript与Unreal Engine深度集成的技术方案，为游戏开发提供了强大的脚本化能力。本文将针对开发过程中可能遇到的典型问题，提供专业的技术分析与解决方案。

内存分配问题

非标准内存分配行为警告

在Windows平台上，Unreal Engine对new操作符的重写存在不符合C++标准的行为：当使用std::nothrow分配长度为0的数组时，会返回nullptr，而标准规定应返回有效指针。

技术影响：

• 可能导致V8等标准兼容运行时误判为内存不足(OOM)而中止
• 影响范围仅限于Windows平台

解决方案： Puerts已内置自动检测和修复机制，当出现以下警告时无需担心：

"new (std::nothrow) int[0] return nullptr, try fix it!"

扩展功能相关

自动绑定模式下扩展函数不可用

问题根源： Puerts模块初始化较早，无法发现后续加载模块中定义的扩展函数。

解决方案： 在所有模块初始化完成后，调用以下API重新扫描扩展方法：

IPuertsModule::Get().InitExtensionMethodsMap();

调试相关

应用挂起等待调试器

原因分析： 这是"Wait for Debugger"选项的预期行为，进程会暂停以等待调试器附加。

解决方案：

1. 如果意外启用，可终止进程
2. 修改配置文件：

Config/DefaultPuerts.ini

将相关选项设为False

类型系统问题

StaticClass返回值异常

TypeScript生成的蓝图类没有StaticClass()方法，调用时会返回继承链中第一个具有此方法的类的UClass。

正确用法：

UE.Class.Load("path/to/your/blueprint/file")

平台相关问题

macOS安全限制错误

错误信息： "Cannot open libv8.dylib because the developer cannot be verified"

解决方案： 在包含.dylib文件的目录下执行：

sudo xattr -r -d com.apple.quarantine *.dylib

打包与运行时问题

蓝图项目编译错误

问题原因： 纯蓝图项目不会自动编译C++插件。

解决方案： 手动生成IDE项目(Xcode/Visual Studio)并进行编译。

打包后字段缺失

技术原理：

• 编辑器环境下FName区分大小写
• 运行时FName不区分大小写

典型场景： 蓝图定义字段count，但运行时首先初始化了Count字段，导致脚本访问count失败。

多线程问题

UE5非法线程构造错误

错误信息： "Construct TypeScript Object TestActor_C_1(...) on illegal thread!"

解决方案： 禁用UE5默认启用的AsyncLoadingThreadEnabled设置。

垃圾回收机制

两种GC模型对比

1. JS管理UE对象：

   • JS GC回收存根(stub)时会释放对UE对象的引用
   • 若无其他引用，UE GC将回收该对象

2. UE管理存根：

   • UE GC回收UE对象时会释放对存根的引用
   • 若无其他引用，JS GC将回收存根

典型UE管理场景：

• TS类继承UE类
• 使用mixin并设置objectTakeByNative
• 使用已弃用的makeUClass

强制GC方法

FJsEnv::LowMemoryNotification();  // 提示V8执行GC
FJsEnv::RequestFullGarbageCollectionForTesting();  // 强制完整GC(性能消耗大)

项目配置问题

打包后脚本不执行

原因： JavaScript文件不是标准的UE资产(*.asset)。

解决方案： 在项目设置→打包→额外非资产目录中添加：

Content/JavaScript

TypeScript版本管理

版本升级指南

1. 修改以下位置的package.json：

   • YourProject/Plugins/Puerts/Content/JavaScript/PuertsEditor
   • YourProject/Content/JavaScript/PuertsEditor

2. 在相应目录执行：

npm install .

版本兼容性：

• 稳定版本：3.4.5、4.4.4、4.7.4
• 测试可用：4.8.2
• 不支持：>4.8.3

蓝图生成问题

完整重新生成声明文件

Puerts.Gen FULL

TS类继承不生成代理蓝图

排查步骤：

1. 检查Puerts命令是否可用：

   puerts ls
   

2. 查找特定TS类：

   puerts ls TsTestActor
   

3. 检查输出中的isBP和processed列

4. 手动触发编译：

   puerts compile <file-id>
   

语法错误处理

蓝图声明文件语法错误

解决方案：

1. 少量问题蓝图：在项目设置→Puerts中将其加入黑名单
2. 大量问题蓝图：为有效蓝图单独生成类型

   Puerts.Gen PATH=/Game/StarterContent
   

性能问题

偶发"调用栈溢出"错误

多线程场景解决方案： 在JsEnv.Build.cs中添加THREAD_SAFE宏。

注意事项：

• V8后端：解决多线程问题
• QJS后端：不支持多线程

结语

本文涵盖了Tencent/puerts项目开发中的常见问题及其解决方案。理解这些技术细节将帮助开发者更高效地使用该框架进行Unreal Engine项目开发。遇到问题时，可根据具体现象参考相应章节进行排查和解决。