尧图网站建设 
PuertsPUER TypeScriptUE 脚本调试实战从开启 V8 Inspector 到 VSCode 附加调试器【免费下载链接】puertsPUER(普洱) Typescript. Lets write your game in UE or Unity with TypeScript.项目地址: https://gitcode.com/GitHub_Trending/pu/puerts本文围绕 PuertsPUER TypeScriptUnreal 引擎插件的调试能力展开Puerts 通过在 V8 虚拟机内部启动一个基于 WebSocket 的 Chrome DevTools Protocol 调试器V8 Inspector让你可以直接用 VSCode 对运行在 UE 中的 TypeScript/JavaScript 代码打断点、观察变量。读完本文你将掌握自动绑定模式与手动创建虚拟机两种场景下开启调试的完整配置方法理解WaitDebugger阻塞等待机制的必要性并能定位调试缓慢等常见问题的根因。一、调试能力的两种启用路径Puerts 中 JavaScript 虚拟机的运行方式分为两类调试的开启方式也随之不同运行方式虚拟机来源调试端口来源典型场景自动绑定模式Automatic Binding ModePuerts 模块自动创建的默认FJsEnv开启继承引擎类功能后系统自动启动项目设置中的Debug Port绝大多数 UE Puerts 项目手动创建虚拟机代码中自行MakeSharedpuerts::FJsEnv传入调试端口构造参数InDebugPort需要自定义脚本根目录、Logger、多个隔离环境的场景无论哪种方式底层机制相同当FJsEnv初始化时携带有效调试端口Puerts 就会调用CreateV8Inspector(InDebugPort, Context)在虚拟机内挂起一个 Inspector 服务见 JsEnvImpl.cpp。调试器随后通过 WebSocket 附加到该端口即可执行标准 CDPChrome DevTools Protocol协议完成断点、变量检查等操作。二、自动绑定模式在项目设置中开启调试自动绑定模式下调试的开启只需在项目设置中勾选打开项目设置Edit - Project Settings进入 Puerts 设置页Plugins - Puerts Settings勾选Debug Enable可选配置Debug Port这些配置项在源码中定义于 PuertsSetting.h是一个UCLASS(config Puerts, defaultconfig)配置类即会被持久化到项目Config/DefaultPuerts.ini。结合源码可以确认各配置项的默认值与含义设置项字段默认值说明Debug EnableDebugEnablefalse是否以调试端口启动默认虚拟机Debug PortDebugPort8080WebSocket 调试端口Wait DebuggerWaitDebuggerfalse启动前阻塞等待调试器附加详见第五节Wait Debugger TimeoutWaitDebuggerTimeout0等待超时0 表示一直等待JavaScript Source RootRootPathJavaScript脚本根目录开启DebugEnable后Puerts 模块会带上调试端口构造默认虚拟机并按需执行WaitDebugger核心逻辑在 PuertsModule.cppif (Settings.DebugEnable) { JsEnv MakeSharedPUERTS_NAMESPACE::FJsEnv( std::make_sharedPUERTS_NAMESPACE::DefaultJSModuleLoader(Settings.RootPath), std::make_sharedPUERTS_NAMESPACE::FDefaultLogger(), DebuggerPortFromCommandLine 0 ? Settings.DebugPort : DebuggerPortFromCommandLine); } ... if (Settings.WaitDebugger) { JsEnv-WaitDebugger(Settings.WaitDebuggerTimeout); }此外从 PuertsModule.cpp 的端口计算逻辑中还能看到两个实用细节命令行覆盖端口引擎参数中传入-JsEnvDebugPort端口可以直接覆盖设置中的DebugPort方便在不改项目的情况下切换调试端口PIE 多实例端口自动偏移在编辑器 Play 模式下每个 PIE 客户端实例的调试端口会按10 × (实例序号1)偏移例如8080 - 8090、8100、8110server 实例则999例如8080 - 9079。这意味着同时运行多个 PIE 实例时不会发生端口冲突但 VSCode 的launch.json也需要对应调整端口才能附加到特定实例。三、手动创建 JavaScript 虚拟机时的调试参数当你在代码中自行创建FJsEnv实例时可以通过构造函数第三个参数传入调试端口从而让该虚拟机以调试模式启动auto JsEnv MakeSharedpuerts::FJsEnv( std::make_sharedpuerts::DefaultJSModuleLoader(TEXT(JavaScript)), // 指定脚本根目录默认 Content/JavaScript std::make_sharedpuerts::FDefaultLogger(), // Logger 对象用于接收 console.log 1337 // 调试端口VSCode 将 Attach 到该端口 ); // 启动 JavaScript 虚拟环境 JsEnv-Start(/*...*/);对照 JsEnv.h 中的完整构造函数签名各参数为FJsEnv(std::shared_ptrIJSModuleLoader InModuleLoader, // 模块加载器决定脚本从何处加载 std::shared_ptrILogger InLogger, // Logger接管 console 输出 int InDebugPort, // 调试端口 0 表示不开启调试 std::functionvoid(const FString) InOnSourceLoadedCallback nullptr, // 源码加载完成回调 const FString InFlags FString(), // V8 启动标志如 --max-old-space-size void* InExternalRuntime nullptr, void* InExternalContext nullptr); // 外部 runtime/context几个值得注意的实现细节端口取负数Port 0时V8InspectorClientImpl会直接跳过 WebSocket 服务初始化即完全不启动调试器见 V8InspectorImpl.cpp因此不传端口的单参数构造FJsEnv(ScriptRoot)就是无调试的普通模式Start的第二个参数是传给入口模块的 C 对象参数列表TArrayTPairFString, UObject*对应IJsEnv::Start接口JsEnv.h若使用 NodeJS 后端调试方式不同FJsEnvImpl在该后端下直接复用 libuv 事件循环见 JsEnvImpl.cpp 中WITH_NODEJS分支本文所述 WebSocket Inspector 主要面向 V8 独立运行时。四、集成 VSCodelaunch.json 与 Attach 流程用 VSCode 调试 Puerts 代码需要在项目.vscode目录下创建launch.jsonYourProject/.vscode/launch.json使用 Node 调试器的attach请求连接到对应端口{ configurations: [ { type: node, name: Puerts Manual Mode Debugger, port: 1337, request: attach }, { type: node, name: Puerts Automatic Binding Mode, port: 8080, request: attach } ] }创建该文件后启动你的 Puerts 工程在 VSCode 中附加对应的调试配置Puerts Manual Mode Debugger 对应第三节端口 1337 的手动虚拟机Puerts Automatic Binding Mode 对应自动绑定模式默认端口 8080。附加成功后即可打断点、检查变量、查看调用栈注意如果没有等待调试器附加在调试器连接建立之前执行的代码将跳过断点。从源码看VSCode 之所以能以type: node的方式附加是因为 Puerts 内置的 Inspector 严格实现了 CDP 的 WebSocket 服务V8InspectorImpl.cpp 基于websocketpp启动监听并提供/json、/json/list、/json/version三个端点返回标准的 DevTools 发现信息Browser: Puerts/v1.0.0、Protocol-Version: 1.1、webSocketDebuggerUrl指向ws://127.0.0.1:端口。这带来两个实用推论Chrome DevTools 也可以直接调试Inspector 启动成功时引擎会向日志输出可点击的调试地址见 V8InspectorImpl.cppStartup Inspector Successfully! Please Open This URL in Debugger Front-End(e.g. Chrome DevTool): devtools://devtools/bundled/inspector.html?v8onlytruews127.0.0.1:端口端口被占用会启动失败构造函数中 WebSocket 服务初始化失败如端口已被占用时只会打印Failed to Startup Inspector错误日志V8InspectorImpl.cpp虚拟机本身正常运行但不带调试能力。遇到无法附加时可先用-JsEnvDebugPort换一个端口验证。另外中文调试指引doc/unreal/zhcn/vscode_debug.md补充了一个 VSCode 侧的设置在 VSCode setting 中搜索auto attach将Debug Node: Auto Attach设为on高版本 VSCode 已无该选项可不设置。五、Waiting For Debugger Attachment 等待调试器附加为什么需要等待调试器通过 WebSocket 连接期间要经历 TCP 握手、WebSocket 升级握手建立连接后调试器与 V8 之间还要交换若干协议信息整个过程大约需要几百毫秒。在这几百毫秒内已经执行过的脚本代码无法命中断点——如果你希望对进入 JavaScript 虚拟环境初期的代码断点就需要让虚拟机在启动前阻塞等待调试器附加完成。自动绑定模式在项目设置中勾选Wait Debugger即可步骤同第二节Edit - Project Settings-Plugins - Puerts Settings- 勾选Wait Debugger可选配置Wait Debugger Timeout。模块初始化时便会调用JsEnv-WaitDebugger(Settings.WaitDebuggerTimeout)见 PuertsModule.cpp。手动创建的虚拟机在Start之前显式调用WaitDebuggerauto JsEnv MakeSharedpuerts::FJsEnv( std::make_uniquepuerts::DefaultJSModuleLoader(TEXT(JavaScript)), std::make_sharedpuerts::FDefaultLogger(), 1337 // 调试端口 ); // 调用此函数等待调试器附加 JsEnv-WaitDebugger(1); // 阻塞等待1 表示超时参数 JsEnv-Start(/*...*/);WaitDebugger是FJsEnv的公开接口声明为void WaitDebugger(double Timeout 0)JsEnv.h转发到IJsEnv抽象接口JsEnv.cpp。从源码结构看其释放等待的时机由 V8 Inspector 的runIfWaitingForDebugger回调驱动——WebSocket 通道真正建立连接时该回调将Connected置位阻塞随即结束见 V8InspectorImpl.cpp。可传入可选的超时参数超时后即使没有调试器附加也会继续启动避免工程在无调试环境如打包后的发布版本调试会话中断时永久卡死。限制当NumberOfJsEnv 1Group 模式多个虚拟机时不支持等待调试器模块会输出警告日志Do not support WaitDebugger in Group Mode!PuertsModule.cpp。六、常见注意事项调试时引擎卡顿Slow Debugger PerformanceUnreal 编辑器默认开启Use Less CPU when in Background当焦点不在 UE 窗口时降低渲染负载。而你在 VSCode 中单步调试时焦点恰恰在 VSCode此时引擎会掉到很低帧率文档示例中约 4 FPS导致调试体验极慢。解决方法是调试期间关闭该选项打开编辑器偏好设置Editor Preferences进入性能设置General - Performance取消勾选Use Less CPU when in Background附加前断点被跳过如果启动后立刻断点失效通常是调试器尚未完成附加见第五节自动模式勾选Wait Debugger手动模式在Start前调用WaitDebugger。端口相关自动模式默认端口8080PuertsSetting.h手动模式端口随构造参数任意指定注意保持与launch.json一致被占用时启动失败可用-JsEnvDebugPort覆盖PIE 多实例会自动偏移端口客户端8080 - 8090/8100…server- 9079附加到特定 PIE 实例时记得同步修改launch.json的端口。七、调试配置速查项目自动绑定模式手动虚拟机开启调试项目设置勾选Debug Enable构造函数第 3 参传端口如1337默认/典型端口8080可改可用-JsEnvDebugPort覆盖自定义等待调试器附加项目设置勾选Wait Debugger可选Wait Debugger TimeoutStart前调用JsEnv-WaitDebugger(Timeout)Group 模式支持等待不支持有警告日志—VSCode 连接launch.jsontype: noderequest: attachport与调试端口一致同左其他前端日志中的devtools://...地址可用 Chrome DevTools 打开同左相关源码参考配置定义 PuertsSetting.h、模块初始化 PuertsModule.cpp、虚拟机接口 JsEnv.h、Inspector 服务实现 V8InspectorImpl.cpp。【免费下载链接】puertsPUER(普洱) Typescript. Lets write your game in UE or Unity with TypeScript.项目地址: https://gitcode.com/GitHub_Trending/pu/puerts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Puerts（PUER TypeScript）UE 脚本调试实战：从开启 V8 Inspector 到 VSCode 附加调试器
PuertsPUER TypeScriptUE 脚本调试实战从开启 V8 Inspector 到 VSCode 附加调试器【免费下载链接】puertsPUER(普洱) Typescript. Lets write your game in UE or Unity with TypeScript.项目地址: https://gitcode.com/GitHub_Trending/pu/puerts本文围绕 PuertsPUER TypeScriptUnreal 引擎插件的调试能力展开Puerts 通过在 V8 虚拟机内部启动一个基于 WebSocket 的 Chrome DevTools Protocol 调试器V8 Inspector让你可以直接用 VSCode 对运行在 UE 中的 TypeScript/JavaScript 代码打断点、观察变量。读完本文你将掌握自动绑定模式与手动创建虚拟机两种场景下开启调试的完整配置方法理解WaitDebugger阻塞等待机制的必要性并能定位调试缓慢等常见问题的根因。一、调试能力的两种启用路径Puerts 中 JavaScript 虚拟机的运行方式分为两类调试的开启方式也随之不同运行方式虚拟机来源调试端口来源典型场景自动绑定模式Automatic Binding ModePuerts 模块自动创建的默认FJsEnv开启继承引擎类功能后系统自动启动项目设置中的Debug Port绝大多数 UE Puerts 项目手动创建虚拟机代码中自行MakeSharedpuerts::FJsEnv传入调试端口构造参数InDebugPort需要自定义脚本根目录、Logger、多个隔离环境的场景无论哪种方式底层机制相同当FJsEnv初始化时携带有效调试端口Puerts 就会调用CreateV8Inspector(InDebugPort, Context)在虚拟机内挂起一个 Inspector 服务见 JsEnvImpl.cpp。调试器随后通过 WebSocket 附加到该端口即可执行标准 CDPChrome DevTools Protocol协议完成断点、变量检查等操作。二、自动绑定模式在项目设置中开启调试自动绑定模式下调试的开启只需在项目设置中勾选打开项目设置Edit - Project Settings进入 Puerts 设置页Plugins - Puerts Settings勾选Debug Enable可选配置Debug Port这些配置项在源码中定义于 PuertsSetting.h是一个UCLASS(config Puerts, defaultconfig)配置类即会被持久化到项目Config/DefaultPuerts.ini。结合源码可以确认各配置项的默认值与含义设置项字段默认值说明Debug EnableDebugEnablefalse是否以调试端口启动默认虚拟机Debug PortDebugPort8080WebSocket 调试端口Wait DebuggerWaitDebuggerfalse启动前阻塞等待调试器附加详见第五节Wait Debugger TimeoutWaitDebuggerTimeout0等待超时0 表示一直等待JavaScript Source RootRootPathJavaScript脚本根目录开启DebugEnable后Puerts 模块会带上调试端口构造默认虚拟机并按需执行WaitDebugger核心逻辑在 PuertsModule.cppif (Settings.DebugEnable) { JsEnv MakeSharedPUERTS_NAMESPACE::FJsEnv( std::make_sharedPUERTS_NAMESPACE::DefaultJSModuleLoader(Settings.RootPath), std::make_sharedPUERTS_NAMESPACE::FDefaultLogger(), DebuggerPortFromCommandLine 0 ? Settings.DebugPort : DebuggerPortFromCommandLine); } ... if (Settings.WaitDebugger) { JsEnv-WaitDebugger(Settings.WaitDebuggerTimeout); }此外从 PuertsModule.cpp 的端口计算逻辑中还能看到两个实用细节命令行覆盖端口引擎参数中传入-JsEnvDebugPort端口可以直接覆盖设置中的DebugPort方便在不改项目的情况下切换调试端口PIE 多实例端口自动偏移在编辑器 Play 模式下每个 PIE 客户端实例的调试端口会按10 × (实例序号1)偏移例如8080 - 8090、8100、8110server 实例则999例如8080 - 9079。这意味着同时运行多个 PIE 实例时不会发生端口冲突但 VSCode 的launch.json也需要对应调整端口才能附加到特定实例。三、手动创建 JavaScript 虚拟机时的调试参数当你在代码中自行创建FJsEnv实例时可以通过构造函数第三个参数传入调试端口从而让该虚拟机以调试模式启动auto JsEnv MakeSharedpuerts::FJsEnv( std::make_sharedpuerts::DefaultJSModuleLoader(TEXT(JavaScript)), // 指定脚本根目录默认 Content/JavaScript std::make_sharedpuerts::FDefaultLogger(), // Logger 对象用于接收 console.log 1337 // 调试端口VSCode 将 Attach 到该端口 ); // 启动 JavaScript 虚拟环境 JsEnv-Start(/*...*/);对照 JsEnv.h 中的完整构造函数签名各参数为FJsEnv(std::shared_ptrIJSModuleLoader InModuleLoader, // 模块加载器决定脚本从何处加载 std::shared_ptrILogger InLogger, // Logger接管 console 输出 int InDebugPort, // 调试端口 0 表示不开启调试 std::functionvoid(const FString) InOnSourceLoadedCallback nullptr, // 源码加载完成回调 const FString InFlags FString(), // V8 启动标志如 --max-old-space-size void* InExternalRuntime nullptr, void* InExternalContext nullptr); // 外部 runtime/context几个值得注意的实现细节端口取负数Port 0时V8InspectorClientImpl会直接跳过 WebSocket 服务初始化即完全不启动调试器见 V8InspectorImpl.cpp因此不传端口的单参数构造FJsEnv(ScriptRoot)就是无调试的普通模式Start的第二个参数是传给入口模块的 C 对象参数列表TArrayTPairFString, UObject*对应IJsEnv::Start接口JsEnv.h若使用 NodeJS 后端调试方式不同FJsEnvImpl在该后端下直接复用 libuv 事件循环见 JsEnvImpl.cpp 中WITH_NODEJS分支本文所述 WebSocket Inspector 主要面向 V8 独立运行时。四、集成 VSCodelaunch.json 与 Attach 流程用 VSCode 调试 Puerts 代码需要在项目.vscode目录下创建launch.jsonYourProject/.vscode/launch.json使用 Node 调试器的attach请求连接到对应端口{ configurations: [ { type: node, name: Puerts Manual Mode Debugger, port: 1337, request: attach }, { type: node, name: Puerts Automatic Binding Mode, port: 8080, request: attach } ] }创建该文件后启动你的 Puerts 工程在 VSCode 中附加对应的调试配置Puerts Manual Mode Debugger 对应第三节端口 1337 的手动虚拟机Puerts Automatic Binding Mode 对应自动绑定模式默认端口 8080。附加成功后即可打断点、检查变量、查看调用栈注意如果没有等待调试器附加在调试器连接建立之前执行的代码将跳过断点。从源码看VSCode 之所以能以type: node的方式附加是因为 Puerts 内置的 Inspector 严格实现了 CDP 的 WebSocket 服务V8InspectorImpl.cpp 基于websocketpp启动监听并提供/json、/json/list、/json/version三个端点返回标准的 DevTools 发现信息Browser: Puerts/v1.0.0、Protocol-Version: 1.1、webSocketDebuggerUrl指向ws://127.0.0.1:端口。这带来两个实用推论Chrome DevTools 也可以直接调试Inspector 启动成功时引擎会向日志输出可点击的调试地址见 V8InspectorImpl.cppStartup Inspector Successfully! Please Open This URL in Debugger Front-End(e.g. Chrome DevTool): devtools://devtools/bundled/inspector.html?v8onlytruews127.0.0.1:端口端口被占用会启动失败构造函数中 WebSocket 服务初始化失败如端口已被占用时只会打印Failed to Startup Inspector错误日志V8InspectorImpl.cpp虚拟机本身正常运行但不带调试能力。遇到无法附加时可先用-JsEnvDebugPort换一个端口验证。另外中文调试指引doc/unreal/zhcn/vscode_debug.md补充了一个 VSCode 侧的设置在 VSCode setting 中搜索auto attach将Debug Node: Auto Attach设为on高版本 VSCode 已无该选项可不设置。五、Waiting For Debugger Attachment 等待调试器附加为什么需要等待调试器通过 WebSocket 连接期间要经历 TCP 握手、WebSocket 升级握手建立连接后调试器与 V8 之间还要交换若干协议信息整个过程大约需要几百毫秒。在这几百毫秒内已经执行过的脚本代码无法命中断点——如果你希望对进入 JavaScript 虚拟环境初期的代码断点就需要让虚拟机在启动前阻塞等待调试器附加完成。自动绑定模式在项目设置中勾选Wait Debugger即可步骤同第二节Edit - Project Settings-Plugins - Puerts Settings- 勾选Wait Debugger可选配置Wait Debugger Timeout。模块初始化时便会调用JsEnv-WaitDebugger(Settings.WaitDebuggerTimeout)见 PuertsModule.cpp。手动创建的虚拟机在Start之前显式调用WaitDebuggerauto JsEnv MakeSharedpuerts::FJsEnv( std::make_uniquepuerts::DefaultJSModuleLoader(TEXT(JavaScript)), std::make_sharedpuerts::FDefaultLogger(), 1337 // 调试端口 ); // 调用此函数等待调试器附加 JsEnv-WaitDebugger(1); // 阻塞等待1 表示超时参数 JsEnv-Start(/*...*/);WaitDebugger是FJsEnv的公开接口声明为void WaitDebugger(double Timeout 0)JsEnv.h转发到IJsEnv抽象接口JsEnv.cpp。从源码结构看其释放等待的时机由 V8 Inspector 的runIfWaitingForDebugger回调驱动——WebSocket 通道真正建立连接时该回调将Connected置位阻塞随即结束见 V8InspectorImpl.cpp。可传入可选的超时参数超时后即使没有调试器附加也会继续启动避免工程在无调试环境如打包后的发布版本调试会话中断时永久卡死。限制当NumberOfJsEnv 1Group 模式多个虚拟机时不支持等待调试器模块会输出警告日志Do not support WaitDebugger in Group Mode!PuertsModule.cpp。六、常见注意事项调试时引擎卡顿Slow Debugger PerformanceUnreal 编辑器默认开启Use Less CPU when in Background当焦点不在 UE 窗口时降低渲染负载。而你在 VSCode 中单步调试时焦点恰恰在 VSCode此时引擎会掉到很低帧率文档示例中约 4 FPS导致调试体验极慢。解决方法是调试期间关闭该选项打开编辑器偏好设置Editor Preferences进入性能设置General - Performance取消勾选Use Less CPU when in Background附加前断点被跳过如果启动后立刻断点失效通常是调试器尚未完成附加见第五节自动模式勾选Wait Debugger手动模式在Start前调用WaitDebugger。端口相关自动模式默认端口8080PuertsSetting.h手动模式端口随构造参数任意指定注意保持与launch.json一致被占用时启动失败可用-JsEnvDebugPort覆盖PIE 多实例会自动偏移端口客户端8080 - 8090/8100…server- 9079附加到特定 PIE 实例时记得同步修改launch.json的端口。七、调试配置速查项目自动绑定模式手动虚拟机开启调试项目设置勾选Debug Enable构造函数第 3 参传端口如1337默认/典型端口8080可改可用-JsEnvDebugPort覆盖自定义等待调试器附加项目设置勾选Wait Debugger可选Wait Debugger TimeoutStart前调用JsEnv-WaitDebugger(Timeout)Group 模式支持等待不支持有警告日志—VSCode 连接launch.jsontype: noderequest: attachport与调试端口一致同左其他前端日志中的devtools://...地址可用 Chrome DevTools 打开同左相关源码参考配置定义 PuertsSetting.h、模块初始化 PuertsModule.cpp、虚拟机接口 JsEnv.h、Inspector 服务实现 V8InspectorImpl.cpp。【免费下载链接】puertsPUER(普洱) Typescript. Lets write your game in UE or Unity with TypeScript.项目地址: https://gitcode.com/GitHub_Trending/pu/puerts创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考