WebAssembly.Exception.prototype.stack

可用性有限

此特性不是基线特性,因为它在一些最广泛使用的浏览器中不起作用。

非标准:此特性未标准化。我们不建议在生产环境中使用非标准特性,因为它们浏览器支持有限,并且可能会更改或被移除。但是,在没有标准选项的特定情况下,它们可以是合适的替代方案。

WebAssembly.Exception 对象的只读 stack 属性可能包含堆栈跟踪。

默认情况下,WebAssembly 代码抛出的异常不包含堆栈跟踪。

如果 WebAssembly 代码需要提供堆栈跟踪,它必须调用 JavaScript 函数来创建异常,并在构造函数中传递 options.traceStack=true 参数。然后,虚拟机可以将堆栈跟踪附加到构造函数返回的异常对象上。

注意:为了提高性能,通常不会从 WebAssembly 代码发送堆栈跟踪。为这些异常添加堆栈跟踪的功能是为开发工具提供的,通常不建议广泛使用。

包含堆栈跟踪的字符串,如果未分配跟踪,则为undefined

堆栈跟踪字符串以 WebAssembly 格式列出了堆栈上每个操作的位置。这是一个人类可读的字符串,指示模块二进制文件中的 URL、调用的函数类型名称、函数索引及其偏移量。它大致格式如下(有关更多信息,请参阅规范中的堆栈跟踪约定

${url}:wasm-function[${funcIndex}]:${pcOffset}

示例

本示例演示了如何从包含堆栈跟踪的 WebAssembly 中抛出异常。

考虑以下 WebAssembly 代码,假定它已编译为名为 example.wasm 的文件。它导入了一个标记,并在内部将其称为 $tagname,并导入了一个它内部称为 $throwExnWithStack 的函数。它导出了 run 方法,外部代码可以调用该方法来调用 $throwExnWithStack(从而调用 JavaScript 函数)。

wat
(module
  ;; import tag that will be referred to here as $tagname
  (import "extmod" "exttag" (tag $tagname (param i32)))

  ;; import function that will be referred to here as $throwExnWithStack
  (import "extmod" "throwExnWithStack" (func $throwExnWithStack (param i32)))

  ;; call $throwExnWithStack passing 42 as parameter
  (func (export "run")
    i32.const 42
    call $throwExnWithStack
  )
)

下面的 JavaScript 代码定义了一个新的标记 tag 和函数 throwExceptionWithStack。在实例化 WebAssembly 模块时,这些会作为 importObject 传递给它。

实例化文件后,代码会调用导出的 WebAssembly run() 方法,该方法会立即抛出异常。然后,堆栈会从 catch 语句中记录下来。

js
const tag = new WebAssembly.Tag({ parameters: ["i32"] });

function throwExceptionWithStack(param) {
  // Note: We declare the exception with "{traceStack: true}"
  throw new WebAssembly.Exception(tag, [param], { traceStack: true });
}

// Note: importObject properties match the WebAssembly import statements.
const importObject = {
  extmod: {
    exttag: tag,
    throwExnWithStack: throwExceptionWithStack,
  },
};

WebAssembly.instantiateStreaming(fetch("example.wasm"), importObject)
  .then((obj) => {
    console.log(obj.instance.exports.run());
  })
  .catch((e) => {
    console.log(`stack: ${e.stack}`);
  });

// Log output (something like):
// stack: throwExceptionWithStack@http://<url>/main.js:76:9
// @http://<url>/example.wasm:wasm-function[3]:0x73
// @http://<url>/main.js:82:38

此代码中最“相关”的部分是创建异常的行:

js
new WebAssembly.Exception(tag, [param], { traceStack: true });

传递 {traceStack: true} 告诉 WebAssembly 虚拟机,它应该将堆栈跟踪附加到返回的 WebAssembly.Exception。如果没有这个,堆栈将是 undefined

浏览器兼容性

另见