调试器对象

当作为构造函数调用时，Debugger 对象创建一个新的 Debugger 实例。

new Debugger([global, ...])

创建一个调试器对象，并将其 addDebuggee 方法应用于给定的每个 global 对象，以将它们添加为初始调试目标。

调试器原型对象的访问器属性

Debugger 实例从其原型继承以下访问器属性

allowUnobservedAsmJS

一个布尔值，指示在此 Debugger 实例的调试目标全局对象中运行的 asm.js 代码是否对调试器 API 处理程序和断点不可见。将其设置为 false 会抑制提前 asm.js 编译器，并强制 asm.js 代码作为普通 JavaScript 运行。这是一个带有 getter 和 setter 的访问器属性。在新建的 Debugger 实例中，它最初为 false。

将此标志设置为 true 用于调试器 API 的子系统（例如 Debugger.Source）的使用，这些子系统用于调试器 API 的目的，而不是逐步调试目标 JavaScript 程序。

collectCoverageInfo

一个布尔值，指示是否应在此 Debugger 实例的每个调试目标中启用代码覆盖率。更改此标志的值将重新编译所有 JIT 代码以添加或删除代码覆盖率检测。当调试目标的任何帧当前在堆栈上处于活动状态时更改此标志将产生异常。

将其设置为 true 将启用代码覆盖率检测，可以通过 Debugger.Script 的 getOffsetsCoverage 函数访问。在某些情况下，代码覆盖率可能会暴露早于修改此标志的信息。代码覆盖率报告是单调的，因此可以在首次启用覆盖率时获取快照，并输出差异。

将其设置为 false 将阻止此 Debugger 实例需要任何代码覆盖率检测，但不能保证检测不存在。

exclusiveDebuggerOnEval

一个布尔值，指示当此实例使用时，其他 Debugger 实例是否应该调用其挂钩函数

  • Debugger.Frame.evalWithBindings,

  • Debugger.Object.executeInGlobalWithBindings

  • Debugger.Object.call 当设置为 true 时，不会通知其他 Debugger 实例。

inspectNativeCallArguments

一个布尔值，设置为 true 以便传递 onNativeCall 挂钩的最后两个参数。

uncaughtExceptionHook

可以是 null 或一个函数，当对调试事件处理程序、断点处理程序或类似函数的调用抛出一些异常时，SpiderMonkey 会调用此函数，我们在此将其称为 调试器异常。在调试器中抛出的异常不会传播到调试目标代码；相反，SpiderMonkey 会调用此函数，将 调试器异常 作为其唯一参数传递，并将 Debugger 实例作为 this 值传递。此函数应返回一个 恢复值，该值决定调试目标应如何继续。

如果未捕获的异常挂钩本身抛出异常 未捕获挂钩异常，SpiderMonkey 会向调试目标抛出一个新的错误对象 向调试目标承认异常，其消息会责备调试器，并包含 未捕获挂钩异常 和原始 调试器异常 的文本描述。

如果 uncaughtExceptionHook 的值为 null，SpiderMonkey 会向调试目标抛出一个异常，其消息会责备调试器，并包含 调试器异常 的文本描述。

将除可调用值或 null 之外的任何内容分配给此属性将抛出一个 TypeError 异常。

（这不是处理调试器错误的理想方法，但这里的希望是，某种后备措施，即使不完美，也能让调试器开发人员的生活更轻松。例如，未捕获的异常挂钩可能可以访问浏览器级别的功能，如 alert 函数，而此 API 的实现没有，从而可以以适合上下文的方式向开发人员呈现调试器错误。）

shouldAvoidSideEffects

一个布尔值，用于请求有副作用的原生代码中止。

如果设置为 true，则 JS::dbg::ShouldAvoidSideEffects(cx) 返回 true。原生代码可以选择加入此功能以支持希望执行无副作用计算的调试器。

调试器处理函数

每个 Debugger 实例都继承了访问器属性，您可以使用这些属性存储处理函数，以便 SpiderMonkey 在调试目标代码中发生给定事件时调用。

当下面描述的事件之一在调试目标代码中发生时，引擎会暂停调试目标并调用每个观察调试目标的 Debugger 实例上的相应调试处理程序。处理函数接收 Debugger 实例作为其 this 值。大多数处理函数可以返回一个 恢复值，指示调试目标的执行应如何继续。

在新 Debugger 实例中，这些属性中的每一个最初都是 undefined。分配给调试处理程序的任何值必须是函数或 undefined；否则将抛出 TypeError。

处理函数在发生事件的同一线程中运行。它们在所属的隔间中运行，而不是在调试目标隔间中运行。

onNewScript(script, global)

新的代码（由 Debugger.Script 实例 script 表示）已加载到调试目标的范围内。

由于每个函数都有自己的 Debugger.Script，与包含它的顶级代码或函数分开，因此加载 JavaScript 代码通常不仅会引入单个脚本，还会引入一个表示顶级代码及其包含的任何函数的脚本树。 onNewScript 挂钩仅报告此类树的根脚本。如有必要，处理函数可以使用脚本的 getChildScripts 方法遍历树并获取所有新引入的脚本。

此方法的返回值被忽略。

onNewPromise(promise)

一个新的 Promise 对象（由 Debugger.Object 实例 promise 引用）已在调试目标的范围内分配。可以使用 Debugger.Object 实例 promise 的 promiseAllocationStack 访问器属性获取 Promise 的分配堆栈。

此处理程序方法应返回一个恢复值，指定调试目标的执行应如何继续。但是，请注意，{ return: value } 恢复值被视为undefined（“正常继续”）；value 将被忽略。

onPromiseSettled(promise)

一个 Promise 对象，由在调试目标作用域内分配的Debugger.Object 实例promise引用，已完成（已fulfilled或已rejected）。可以使用 Promise 相关的Debugger.Object 实例promise的访问器属性获取 Promise 的状态、完成或拒绝值以及分配和解析堆栈。

此处理程序方法应返回一个恢复值，指定调试目标的执行应如何继续。但是，请注意，{ return: value } 恢复值被视为undefined（“正常继续”）；value 将被忽略。

onDebuggerStatement(frame)

调试目标代码在frame中执行了一个debugger语句。此方法应返回一个恢复值，指定调试目标的执行应如何继续。

onEnterFrame(frame)

堆栈帧frame即将开始执行代码。（当然，frame当前是最年轻的可见帧。）此方法应返回一个恢复值，指定调试目标的执行应如何继续。

SpiderMonkey 仅调用onEnterFrame 来报告可见的、非"debugger"帧。

onNativeCall(callee, reason)

正在从调试目标领域调用本地函数。callee 是正在调用的函数的 [Debugger.Object]，reason 是一个字符串，描述调用该函数的原因，并且具有以下值之一

get：本地函数是正在访问的属性的 getter。 set：本地函数是正在写入的属性的 setter。 call：任何不属于上述类别的调用。

object 是对调用本地方法的对象（如果有）的Debugger.Object引用。args 是传递给本地函数的参数数组的Debugger.Object。

只有当Debugger.inspectNativeCallArguments 设置为 true 时，才会传递最后两个参数object 和args。

此方法应返回一个恢复值，指定调试目标的执行应如何继续。如果为构造函数调用覆盖了返回值，则它必须是对象。

只有当执行位于与具有onNativeCall钩子的调试器关联的调试器评估内部时，SpiderMonkey 才会调用onNativeCall钩子。此类评估方法包括Debugger.Object.apply、Debugger.Object.call、Debugger.Object.executeInGlobal、Debugger.Frame.eval以及关联的方法。

另外，在调用Debugger.Object.apply、Debugger.Object.call、Debugger.Object.executeInGlobal、Debugger.Frame.eval以及关联的方法期间触发的任何 Debugger 钩子，都只会触发执行评估的 Debugger 对象。

onExceptionUnwind(frame, value)

异常value已被抛出，并已传播到frame；frame 是剩余的最年轻的堆栈帧，并且是调试目标帧。此方法应返回一个恢复值，指定调试目标的执行应如何继续。如果它返回undefined，则异常将照常继续传播：如果frame中的控制位于try块中，则控制跳转到相应的catch或finally块；否则，frame将被弹出，异常将传播到frame的调用者。

当异常的传播导致控制进入finally块时，异常将被暂时搁置。如果finally块正常完成，则异常将恢复传播，并且调试器的onExceptionUnwind处理程序将在同一帧中再次被调用。（另一种可能性是finally块由于return、continue或break语句或新异常而退出。在这些情况下，旧异常不会继续传播；它将被丢弃。）

由于过度递归或内存不足异常导致帧展开时，不会调用此处理程序。

sourceHandler(ASuffusionOfYellow)

此方法永远不会被调用。如果它被调用，则表明已证明存在矛盾，调试器可以自由地假设所有内容都是正确的。

onError(frame, report)

SpiderMonkey 即将在frame中报告错误。Report 是一个描述错误的对象，具有以下属性

  • message 完全格式化的错误消息。

  • file 如果存在，则为源文件名、URL 等。（如果此属性存在，则line属性也将存在，反之亦然。）

  • line 如果存在，则为发生错误的源代码行号。

  • lineText 如果存在，则为有问题的行的源代码。

  • offset 发生错误的字符在 lineText 中的索引。

  • warning 如果是警告，则存在且为 true；否则不存在。

  • strict 如果此错误或警告是由于 strict 选项导致的（不要与 ES strict 模式混淆），则存在且为 true。

  • exception 如果将抛出异常，则存在且为 true；否则不存在。

  • arguments 一个字符串数组，表示替换到错误消息中的参数。

此方法的返回值被忽略。

onNewGlobalObject(global)

已创建了一个新的全局对象global。

此处理程序方法应返回一个恢复值，指定调试目标的执行应如何继续。但是，请注意，{ return: value } 恢复值被视为undefined（“正常继续”）；value 将被忽略。（允许处理程序用其自己的值替换新的全局对象似乎没有用。）

此处理程序方法仅适用于在特权代码（Firefox 中的“chrome”）中运行的调试器。此Debugger API 提供的大多数函数仅观察 API 用户可访问的那些全局变量中的活动，从而对Debugger的范围施加基于能力的限制。但是，onNewGlobalObject 方法允许 API 用户监视 JavaScript 系统（SpiderMonkey 术语中的“JSRuntime”）中发生的任何全局对象创建，从而摆脱基于能力的限制。因此，onNewGlobalObject 仅适用于特权代码。

请注意，即使Debugger的onNewGlobalObject钩子的存在可能具有任意副作用，但垃圾回收器也不会认为钩子的存在是保持Debugger存活的充分理由。因此，在未根植的Debugger上使用onNewGlobalObject的代码的行为可能会受到垃圾回收器活动的影响，并且不完全是确定性的。

Debugger 原型对象的函数属性

下面描述的函数只能使用引用Debugger实例的this值调用；它们不能用作其他类型对象的方法。

addDebuggee(global)

将由global指定的全局对象添加到此Debugger实例正在调试的全局对象集中。如果指定的全局对象已经是调试目标，则此操作无效。返回此Debugger的Debugger.Object实例，该实例引用指定的全局对象。

值global可以是以下任何内容

  • 全局对象。

  • HTML5 WindowProxy对象（Firefox 术语中的“外部窗口”），将其视为传递了浏览上下文活动文档（“内部窗口”）的Window对象。

  • 对象的跨区包装器；我们将先前的规则应用于包装的对象。

  • 属于此Debugger实例的Debugger.Object实例；我们将先前的规则应用于被引用者。

  • 任何其他类型的值都被视为TypeError。（请注意，在解析给定的global参数的过程中，每个规则只应用一次。因此，例如，引用第二个引用全局对象的Debugger.Object的Debugger.Object不会为本函数的目的指定该全局对象。）

由global指定的全局对象必须位于与此Debugger实例本身不同的区隔中。如果添加指定的全局对象的区隔会创建调试器和调试目标区隔的循环，则此方法将抛出错误。

此方法返回Debugger.Object实例，其被引用者是指定的全局对象。

Debugger实例不会持有对其调试目标全局对象的强引用：如果调试目标全局对象无法通过其他方式访问，则它将从Debugger的调试目标集中删除。（当然，此方法返回的Debugger.Object实例确实持有对已添加全局对象的强引用。）

如果此调试器正在跟踪分配站点并且无法跟踪global的分配站点，则此方法将抛出Error。

addAllGlobalsAsDebuggees()

此方法类似于addDebuggee，但会将所有区隔中的所有全局对象添加到此Debugger实例的调试目标集中。请注意，它会跳过此调试器的区隔。

如果此调试器正在跟踪分配站点并且无法跟踪某些全局对象的分配站点，则此方法将抛出Error。否则，此方法将返回undefined。

此方法仅适用于在特权代码（Firefox 中的“chrome”）中运行的调试器。此 Debugger API 提供的大多数函数仅观察 API 用户可访问的那些全局变量中的活动，从而对 Debugger 的访问范围施加基于功能的限制。但是，addAllGlobalsAsDebuggees 方法允许 API 用户监视 JavaScript 系统（SpiderMonkey 术语中的“JSRuntime”）中任何位置发生的全局对象创建，从而摆脱基于功能的限制。因此，addAllGlobalsAsDebuggees 仅适用于特权代码。

removeDebuggee(global)

从此 Debugger 实例的调试对象集中移除由 global 指定的全局对象。返回 undefined。

此方法使用与 addDebuggee 相同的规则解释 global。

从此 Debugger 中移除一个全局对象作为调试对象，会清除该全局对象中属于该 Debugger 的所有断点。

removeAllDebuggees()

从此 Debugger 实例的调试对象集中移除所有全局对象。返回 undefined。

hasDebuggee(global)

如果由 global 指定的全局对象是此 Debugger 实例的调试对象，则返回 true。

此方法使用与 addDebuggee 相同的规则解释 global。

getDebuggees()

返回一个包含不同 Debugger.Object 实例的数组，其引用对象是此 Debugger 实例正在调试的所有全局对象。

由于 Debugger 实例不持有对其调试对象全局变量的强引用，因此，如果调试对象全局变量在其他方面不可访问，则它可能会随时从此方法返回的数组中删除。

getNewestFrame()

返回一个 Debugger.Frame 实例，该实例引用调用线程堆栈上最年轻的 可见帧，如果堆栈上没有可见帧，则返回 null。

findSources()

返回所有调试对象脚本的所有 Debugger.Source 实例的数组。

请注意，结果可能包含调试对象不再使用的源代码：例如，已完成运行的 eval 代码或不可访问函数的源代码。这些源代码是否出现可能会受到垃圾回收器行为的影响，因此此函数的结果并非完全确定性的。

findScripts([query])

返回所有与 query 匹配的调试对象脚本的 Debugger.Script 实例数组。每个实例在数组中仅出现一次。Query 是一个对象，其属性限制了返回哪些脚本；脚本必须满足 query 给出的所有条件才能返回。如果省略 query，我们将返回所有调试对象脚本的 Debugger.Script 实例。

Query 可以具有以下属性

  • url

    脚本的 url 属性必须等于此值。

  • source

    脚本的 source 属性必须等于此值。

  • line

    脚本必须至少部分重叠给定的源代码行。如果存在此属性，则 url、source 或 displayURL 属性也必须存在。

  • start 和 end

    这些属性定义了脚本必须至少部分重叠的目标源代码范围。其值必须是一个具有 line 属性和可选的基于 1 的 column 属性的对象。脚本必须至少部分重叠范围 [start.line, end.line] 才能包含在结果中。

    如果提供了 start.column 属性，则目标范围的起始行仅包含列 [start.column, Infinity)。如果提供了 end.column 属性，则目标范围的结束行仅包含 [1, end.column] 列。

    示例 query：{ start: { line: 7, column: 11 }, end: { line: 13, column: 5} }

    如果存在这些属性，则它们优先于 line。

    这些属性必须一起存在。如果存在，则 url、source 或 displayURL 属性也必须存在。

  • innermost

    如果存在此属性且为 true，则脚本必须是最内层重叠目标源代码范围的脚本；将省略封闭代码的脚本。

  • global

    脚本必须在给定全局对象的范围内。如果此属性的值是属于此 Debugger 实例的 Debugger.Object 实例，则使用其引用对象。如果该对象不是全局对象，则使用分配该对象的全局对象。

query 的所有属性都是可选的。传递一个空对象将返回所有调试对象代码脚本。

请注意，结果可能包含调试对象不再使用的脚本的 Debugger.Script 实例，例如，已完成运行的 eval 代码或不可访问函数的脚本。这些脚本是否出现可能会受到垃圾回收器行为的影响，因此此函数的行为并非完全确定性的。

findSourceURLs()

返回一个字符串数组，其中包含在任何调试对象领域中创建的所有已知源代码的 URL。该数组将为每个源代码包含一个条目，因此可能存在重复项。领域的 URL 偶尔会被清除，并且返回的数组可能不完整。

findObjects([query])

返回一个 Debugger.Object 实例数组，这些实例引用在与 query 匹配的调试对象全局变量的范围内分配的每个活动对象。每个实例在数组中仅出现一次。Query 是一个对象，其属性限制了返回哪些对象；对象必须满足 query 给出的所有条件才能返回。如果省略 query，我们将返回所有在调试对象全局变量范围内分配的对象的 Debugger.Object 实例。

query 对象可以具有以下属性

  • class

    如果存在字符串值，则仅返回其内部 [[Class]] 的名称与给定字符串匹配的对象。请注意，在某些情况下，给定构造函数的原型对象具有与其引用实例相同的 [[Class]]，但本身不能用作该类的有效实例。通过类名收集对象的代码可能需要进一步检查它们，然后再尝试使用它们。

    如果存在 Debugger.Object 值，则仅返回在原型链中具有给定对象作为构造函数或原型的对象。请注意，具有动态原型（例如 Proxy）的对象无法与此查询匹配，因为访问此类对象的原型可能会产生一些副作用。另请注意，当前具有 null 原型的对象无法与此查询匹配。

query 的所有属性都是可选的。传递一个空对象将返回调试对象全局变量中的所有对象。

与 findScripts 不同，此函数是确定性的，并且永远不会返回引用以前不可访问的对象（尚未被收集）的 Debugger.Objects。

clearBreakpoint(handler)

移除在此 Debugger 实例中设置的所有使用 handler 作为其处理程序的断点。请注意，如果使用其他处理程序对象的断点设置在与 handler 相同的位置，则它们将保留在原位。

clearAllBreakpoints()

移除使用此 Debugger 实例设置的所有断点。

findAllGlobals()

返回一个 Debugger.Object 实例数组，这些实例引用此 JavaScript 实例中存在的所有全局对象。

此调用的结果可能会受到 JavaScript 实现细节的非确定性方式的影响。该数组可能包含引用调试对象或系统中任何其他代码实际上无法访问的全局对象的 Debugger.Object 实例。（当然，一旦函数返回，数组的 Debugger.Object 实例会强烈引用它们引用的全局变量。）

此处理程序方法仅适用于在特权代码（Firefox 中的“chrome”）中运行的调试器。此 Debugger API 提供的大多数函数仅观察 API 用户可访问的那些全局变量中的活动，从而对 Debugger 的访问范围施加基于功能的限制。但是，findAllGlobals 允许 API 用户查找 JavaScript 系统（SpiderMonkey 术语中的“JSRuntime”）中任何位置的所有全局对象，从而摆脱基于功能的限制。因此，findAllGlobals 仅适用于特权代码。

makeGlobalObjectReference(global)

返回其引用对象是 global 指定的全局对象的 Debugger.Object，而无需将指定的全局对象添加为调试对象。如果 global 未指定全局对象，则抛出 TypeError。使用与 Debugger.prototype.addDebuggee 相同的规则确定 global 指定哪个全局对象。

adoptDebuggeeValue(value)

给定一个由任意 Debugger 拥有的调试对象值 value，返回由此 Debugger 拥有的等效调试对象值。

如果value是原始值，则直接返回。如果value是某个任意Debugger所拥有的Debugger.Object，则返回一个由当前Debugger所拥有的等效Debugger.Object。否则，如果value是其他类型的对象，因此不是有效的调试目标值，则抛出TypeError异常。

adoptFrame(frame)

给定类型为Debugger.Frame的frame，该frame由某个任意Debugger拥有，返回一个由当前Debugger所拥有的等效Debugger.Frame。如果frame与一个不是采用调试器的调试目标的调试目标相关联，则此方法将抛出异常。

adoptSource(source)

给定类型为Debugger.Source的source，该source由某个任意Debugger拥有，返回一个由当前Debugger所拥有的等效Debugger.Source。

enableAsyncStack(global)

为由global指定的全局对象的领域启用异步栈捕获。

disableAsyncStack(global)

为由global指定的全局对象的领域禁用异步栈捕获。

enableUnlimitedStacksCapturing(global)

允许为由global指定的全局对象的领域捕获超过50个堆栈跟踪，即使它不是调试目标。

disableUnlimitedStacksCapturing(global)

不允许为由global指定的全局对象的领域捕获超过50个堆栈跟踪，除非它是调试目标。

Debugger对象的静态方法

下面描述的函数没有使用this值调用。

isCompilableUnit(source)

：给定一段由source指定的源代码字符串，如果该字符串可以通过添加更多行变成有效的JavaScript语句，则返回false。否则返回true。目的是支持交互式编译 - 在缓冲区中累积行，直到isCompilableUnit为true，然后将其传递给编译器。