SuperAPI AI 工具集

devtools-source-maps

编程与开发

查看项目

更新于 11-06 20:12

技能介绍

本技能说明如何在 DevTools 前端中把运行时坐标正确映射到原始源码位置,并渲染结构化堆栈跟踪或符号化错误。

一、主要规则

  1. 不要手动解析原始错误堆栈:不要按换行符拆分,也不要使用自制的正则表达式解析堆栈跟踪,应使用 DebuggerWorkspaceBinding 提供的辅助方法进行结构化解析与转换。
  2. 释放订阅:SymbolizedError 等模型会订阅实时位置,当使用方(例如挂件或列表)销毁时,必须调用 .dispose(),以避免内存泄漏。
  3. 优先使用现成组件:不要自行格式化或渲染调用帧;原始堆栈使用 StackTracePreviewContent,完整错误使用 SymbolizedErrorWidget。

二、核心抽象

  1. StackTrace 模型(front_end/models/stack_trace/):调用栈的结构化表示,包含同步与异步片段。StackTrace、ParsedErrorStackTrace、DebuggableStackTrace 在原始来源完全解析或更新时派发 StackTrace.Events.UPDATED 事件。Frame 表示单个帧,包含 uiSourceCode、url、行/列信息、未翻译的 rawName、翻译后的名称和内联信息。
  2. SymbolizedError 模型(front_end/models/bindings/SymbolizedError.ts):表示完全符号化错误的联合类型。SymbolizedErrorObject 包含错误消息、stackTrace(ParsedErrorStackTrace 类型)以及可选的 cause(另一个 SymbolizedError),还持有编译或求值时的 syntaxErrorLocation;UnparsableError 是解析失败时的回退类型。

三、DebuggerWorkspaceBinding 核心 API 位置转换: const uiLocation = await Bindings.DebuggerWorkspaceBinding.instance().rawLocationToUILocation(rawLocation); 从协议堆栈跟踪(Runtime 域)生成堆栈: const stack = await Bindings.DebuggerWorkspaceBinding.instance().createStackTraceFromProtocolRuntime(protocolStackTrace, target); 从调试器暂停详情生成堆栈: const stack = await Bindings.DebuggerWorkspaceBinding.instance().createStackTraceFromDebuggerPaused(pausedDetails, target); 从原始错误堆栈字符串生成堆栈: const stack = await Bindings.DebuggerWorkspaceBinding.instance().createStackTraceFromErrorStackLikeString(target, stackString, exceptionDetails); 从远程错误对象生成符号化错误: const symbolizedError = await Bindings.DebuggerWorkspaceBinding.instance().createSymbolizedError(remoteObject, exceptionDetails);

四、UI 组件

  1. StackTracePreviewContent:在 Shadow DOM 中渲染结构化 StackTrace,处理可展开 UI,并折叠被忽略列表中的文件。示例代码(依次引用 utils.js、workspace.js,创建组件、设置 stackTrace 与 options,包括 expandable、showColumnNumber、ignoreListManager,再挂载 element)按资料原文保留。
  2. SymbolizedErrorWidget:显示完整 SymbolizedError,包括递归因果链(“Caused by: ...” )和语法错误位置。示例代码(引用 panels.js、workspace.js,创建组件、设置 error 与 ignoreListManager,再挂载 element)按资料原文保留。

五、验证清单

  1. 检查内存泄漏:确认使用方组件清理时调用了 symbolizedError.dispose()。
  2. 忽略列表支持:确保组件设置了 ignoreListManager。
  3. WASM/内联支持:检查内联帧与 WebAssembly 帧能否通过原始 Source Map 正确映射。