#Error.captureStackTrace S2

#Error.captureStackTrace

阶段: 第 2 阶段

** champions**: Matthew Gaudet (Mozilla)， Daniel Minor (Mozilla)

V8 已经有一个非标准的 栈跟踪 API 一段时间了。

2023 年 8 月，JSC 也发布了这个方法

这个方法 现在变成了一个 Web 兼容性问题，因此我们现在应该将其标准化。

注意：我们在等待两个相关提案的结果时暂停了本提案的工作：Error option limit 和 Error option framesAbove。如果这些提案推进、实现并替换了当前 Error.captureStackTrace 的足够多使用场景，我们可能可以避免将其标准化。

#Error.captureStackTrace

引用 V8 文档 中的内容：

自定义异常的堆栈跟踪收集

用于内置错误的堆栈跟踪机制是通过一个通用的堆栈跟踪收集 API 实现的，该 API 也可供用户脚本使用。该函数

Error.captureStackTrace(error, constructorOpt)

为给定的错误对象添加一个 stack 属性，该属性产生调用 captureStackTrace 时的堆栈跟踪。通过 Error.captureStackTrace 收集的堆栈跟踪会立即收集、格式化并附加到给定的错误对象上。

可选的 constructorOpt 参数允许您传入一个函数值。在收集堆栈跟踪时，该函数的最顶层调用以上的所有帧（包括该调用）都会从堆栈跟踪中排除。这对于隐藏对用户不太有用的实现细节非常有用。定义捕获堆栈跟踪的自定义错误的通常方式是：

function MyError() {
  Error.captureStackTrace(this, MyError);
  // 其他初始化代码写在这里。
}

传入 MyError 作为第二个参数意味着对 MyError 的构造函数调用不会出现在堆栈跟踪中。

请注意，尽管文档说明堆栈跟踪会立即收集和格式化，但在 V8 中并非如此，因为存在 Error.prepareStackTrace 方法。格式化是在首次访问 stack 时才执行的，以避免花费时间格式化一个可能永远不会被访问的堆栈跟踪。

#实现分歧

不幸的是，JSC 的实现与 V8 的实现存在分歧：

• JSC 为提供的对象附加一个字符串值属性，而 V8 则安装它们的堆栈 getter 函数。
• 它使用 JSC 的堆栈字符串格式。

由于 Error.prepareStackTrace 以及 V8 中现有的惰性格式化堆栈行为，V8 不太可能切换到使用数据属性。

堆栈字符串内容的文本应该大致如下：

堆栈字符串的内容是 执行上下文栈 的文本表示，但实际格式和内容由实现定义，不应依赖它们在各个实现之间相同。

#相关工作

• Error Stacks 提案与本提案在很大程度上是正交的，但它将提供讨论堆栈字符串的框架和文本，因为目前规范基本上不讨论堆栈。然而，对于本提案，我认为我们不需要指定堆栈字符串的内容。
• Error Stack Accessor 提案可能是规范开始讨论堆栈的另一条途径。请注意，Error.captureStackTrace 适用于任何对象，而堆栈访问器提案仅适用于 Error 实例，因此这两个提案解决的是不同的问题。

#历史

• 2025 年 11 月提交，并达到第 2 阶段 笔记
• 2025 年 2 月提交，并达到第 1 阶段 笔记
• 2025 年 7 月提交 笔记
• 在 2025 年 10 月 8 日的 TG3 每周会议上进行了讨论。