three.js TSL StackTrace：为节点系统提供可追溯的调试堆栈工具

three.js TSL StackTrace为节点系统提供可追溯的调试堆栈工具【免费下载链接】three.jsJavaScript 3D Library.项目地址: https://gitcode.com/GitHub_Trending/th/three.js本篇聚焦 three.js 节点系统TSL中的StackTrace类讲清它的构造参数、isStackTrace/stack属性与getLocation()/getError()两个方法的实际行为并结合 src/nodes/core/StackTrace.js 的源码展开跨浏览器堆栈解析、库帧过滤等实现细节以及它在Node、NodeError、utils.js日志体系中的完整调用链帮助你在编写 TSL 着色器代码时快速定位报错发生的具体文件与行号。一、StackTrace 是什么StackTrace是一个用于调试目的的堆栈跟踪类官方文档将其定义为 Class representing a stack trace for debugging purposes参见 docs/pages/StackTrace.html.md。它解决的核心问题是TSL 代码以闭包和函数式 API 形式组合节点一旦类型不匹配、参数错误原生Error堆栈里会混入大量 three.js 内部实现帧很难看出我的哪一行代码写错了。StackTrace通过捕获、解析并过滤当前堆栈把用户代码位置以结构化数组的形式提取出来供日志系统拼接成可读的错误信息。二、构造器new StackTrace( stackMessage : Error | string | null )创建一个StackTrace实例通过捕获并过滤当前堆栈来工作。参数说明stackMessage可选的堆栈跟踪用于替代实时捕获的新堆栈。它可以是Error对象、堆栈字符串或null默认值为null。当传入值非空时直接解析该值否则执行new Error().stack现场捕获。对应源码 src/nodes/core/StackTrace.js#L62-L80constructor( stackMessage null ) { this.isStackTrace true; this.stack getFilteredStack( stackMessage ? stackMessage : new Error().stack ); }这个设计的实用含义是你既可以在报错现场即时构造new StackTrace()也可以在拿到一段已序列化/远程上报的堆栈文本后将其还原为结构化的帧数组再次解析——这对异步日志、跨环境错误上报场景很关键。三、属性.isStackTrace : boolean (readonly)用于类型测试的标志位默认值为true。three.js 的日志系统正是靠它来区分第二个参数是不是堆栈对象从而决定输出格式。.stack : Array.{fn: string, file: string, line: number, column: number}过滤后的堆栈帧数组每帧包含函数名fn、文件名file、行号line、列号column四个字段。注意经过过滤后file只保留文件名不含完整路径且查询参数如 Vite HMR 的?xxx后缀会被清除。四、堆栈解析与过滤的源码实现4.1 跨浏览器格式兼容不同浏览器生成的堆栈行格式不同源码用一个正则同时兼容 Chrome 与 Firefox 两种风格src/nodes/core/StackTrace.js#L13-L50// Chrome: at functionName (file.js:1:2) or at file.js:1:2 // Firefox: functionNamefile.js:1:2 const regex /(?:at\s(.?)\s\()?(?:(.?))?([^\s()]):(\d):(\d)/;逐行解析逻辑return stack.split( \n ) .map( line { const match line.match( regex ); if ( ! match ) return null; // 行格式无效则跳过 // Chrome: match[1], Firefox: match[2] const fn match[ 1 ] || match[ 2 ] || ; const file match[ 3 ].split( ? )[ 0 ]; // 清理文件名Vite/HMR const lineNum parseInt( match[ 4 ], 10 ); const column parseInt( match[ 5 ], 10 ); // 从完整路径中只提取文件名 const fileName file.split( / ).pop(); return { fn: fn, file: fileName, line: lineNum, column: column }; } ) .filter( frame { // 只保留有效且不在忽略列表中的帧 return frame ! IGNORED_FILES.some( regex regex.test( frame.file ) ); } );两个值得注意的工程细节file.split( ? )[ 0 ]显式处理 Vite/HMR 场景下文件名携带查询串的问题保证 dev server 环境下解析结果稳定。file.split( / ).pop()把完整路径截成文件名因为后续过滤规则只按文件名匹配。4.2 库内帧过滤只看你的代码文件顶部的忽略列表src/nodes/core/StackTrace.js#L1-L7// Pre-compiled RegExp patterns for ignored files const IGNORED_FILES [ /^StackTrace\.js$/, /^TSLCore\.js$/, /^.*Node\.js$/, /^three\.webgpu.*\.js$/ ];含义是StackTrace.js自身、TSLCore.js、所有以Node.js结尾的节点类文件、以及three.webgpu*.js打包产物中的帧全部被剔除。从源码结构看这是为了让最终报错信息中出现的帧尽量都是用户自己写的模块从而把错在哪直接指向你的代码文件而不是库内部。五、方法详解5.1.getLocation() : string返回堆栈顶部帧的格式化位置字符串。实现src/nodes/core/StackTrace.js#L87-L102getLocation() { if ( this.stack.length 0 ) { return [Unknown location]; } const mainStack this.stack[ 0 ]; const fn mainStack.fn; const fnName fn ? ${ fn }() at : ; return ${fnName}${mainStack.file}:${mainStack.line}; // :${mainStack.column} }行为要点若过滤后没有任何有效帧返回[Unknown location]而不是抛错输出形如myFunction() at myShader.js:42即把函数名与文件:行号拼成一行源码注释中保留了列号占位// :${mainStack.column}说明列号信息在getError()中完整保留而getLocation()为了单行简洁只展示到行号。5.2.getError( message ) : string返回包含完整堆栈的错误消息字符串。实现src/nodes/core/StackTrace.js#L110-L135getError( message ) { if ( this.stack.length 0 ) { return message; } // Output: Error: message\n at functionName (file.js:line:column) const stackString this.stack.map( frame { const location ${ frame.file }:${ frame.line }:${ frame.column }; if ( frame.fn ) { return at ${ frame.fn } (${ location }); } return at ${ location }; } ).join( \n ); return ${ message }\n${ stackString }; }输出格式刻意模仿浏览器原生堆栈样式例如THREE.error TSL: Unsupported type: someType at myTslFunction (myModule.js:17:5) at setupMaterial (sceneSetup.js:88:3)若堆栈为空则原样返回message保证调用方拿到的一定是字符串无需判空。六、StackTrace 在 three.js 节点系统中的实际用法6.1 随节点创建的堆栈捕获Node.captureStackTrace在 src/nodes/core/Node.js#L154-L166 中Node构造器持有stackTrace字段并受全局开关控制this.stackTrace null; if ( Node.captureStackTrace true ) { this.stackTrace new StackTrace(); }开关默认关闭src/nodes/core/Node.js#L1215Node.captureStackTrace false;也就是说默认情况下每个 TSL 节点不会记录创建位置的堆栈。把Node.captureStackTrace置为true后每个节点实例在创建时都会捕获一次堆栈调试器就能回答这个节点是在哪行代码里 new 出来的。这是一种典型的默认关闭、按需开启的设计——因为每个节点都要执行new Error()与字符串解析开启后会有可见的构造开销只建议在调试疑难问题如节点意外重复生成、材质缓存异常时临时打开。6.2 结构化错误对象NodeErrorsrc/nodes/core/NodeError.js 把StackTrace与标准Error组合起来class NodeError extends Error { constructor( message, stackTrace null ) { super( message ); this.name NodeError; this.stackTrace stackTrace; } }它让节点相关的错误既保留原生Error.message/name语义又附带一份经StackTrace过滤后的结构化堆栈便于程序化读取stackTrace.stack数组。6.3 日志体系中的增强输出three.js 全局的warn/error日志函数src/utils.js#L229-L327是StackTrace最主要的使用方isStackTrace类型测试warn和error的第一个参数若是StackTrace实例则调用stackTrace.getError( message )输出带完整堆栈的单条字符串const stackTrace params[ 0 ]; if ( stackTrace stackTrace.isStackTrace ) { console.error( stackTrace.getError( message ) ); } else { console.error( message, ...params ); }TSL 前缀消息的自动定位enhanceLogMessage()对以TSL:开头的消息做增强——若附带了堆栈对象就把getLocation()追加到消息末尾否则提示用户开启捕获开关if ( typeof message string message.startsWith( TSL: ) ) { const stackTrace params[ 1 ]; if ( stackTrace stackTrace.isStackTrace ) { params[ 0 ] stackTrace.getLocation(); } else { params[ 1 ] Stack trace not available. Enable THREE.Node.captureStackTrace to capture stack traces.; } }6.4 典型调用点在 TSL 核心与节点工具中new StackTrace()被广泛用于类型/参数校验失败现场例如src/nodes/tsl/TSLCore.jsassign未处于Fn()上下文时报TSL: No stack defined for assign operation. Make sure the assign is inside a Fn()., new StackTrace()参数长度不足或超限、Invalid parameter for the type、Invalid layout type.等错误同样附带StackTracesrc/nodes/core/NodeUtils.js#L173类型转换失败时报TSL: Unsupported type: ...src/nodes/core/StackNode.js#L129TSL: Invalid node added to stack.src/nodes/gpgpu/ComputeNode.js#L255compute 的workgroupSize元素个数或取值非法src/nodes/core/ParameterNode.js#L59TSL: Member ... not found in struct ...。这些调用点遵循统一模式在用户代码执行到的 API 边界处捕获堆栈再由IGNORED_FILES过滤掉库内部帧最终控制台输出中剩下的帧基本都是你的源文件——这正是StackTrace在整个调试链路中的价值闭环。七、实战要点小结场景做法依据报错时想知道精确位置依赖 TSL 校验自动附带的StackTrace直接阅读控制台输出的文件:行:列src/utils.js、src/nodes/core/StackTrace.js需要知道某节点在哪行被创建临时设置Node.captureStackTrace truesrc/nodes/core/Node.js#L1215拿到远程/异步上报的堆栈字符串再次解析new StackTrace( stackString )构造器stackMessage参数判断一个值是否为堆栈对象检查obj.isStackTraceisStackTrace只读标志需要注意的是StackTrace解析依赖Error().stack的浏览器格式Chrome 的at fn (file:line:col)与 Firefox 的fnfile:line:col且过滤规则针对文件名匹配因此在非浏览器环境如 Node 服务端预处理中行为可能不同适用前提是浏览器端的 three.js WebGPU/TSL 使用场景。八、参考文件文档docs/pages/StackTrace.html.md核心实现src/nodes/core/StackTrace.js错误封装src/nodes/core/NodeError.js捕获开关src/nodes/core/Node.js日志增强src/utils.js典型调用点src/nodes/tsl/TSLCore.js、src/nodes/core/NodeUtils.js【免费下载链接】three.jsJavaScript 3D Library.项目地址: https://gitcode.com/GitHub_Trending/th/three.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考