Error.captureStackTrace()

Статический метод Error.captureStackTrace() устанавливает информацию о стеке вызовов в предоставленный объект в виде свойства stack.

Синтаксис

Error.captureStackTrace(object)
Error.captureStackTrace(object, constructor)

Параметры

object

Объект, к которому будет добавлено свойство stack.

constructor Необязательный

Функция, обычно конструктор, где был создан object. При сборе трассировки стека все фреймы выше самого верхнего вызова этой функции, включая этот вызов, исключаются из трассировки стека.

Возвращаемое значение

Нет (undefined).

object модифицируется на месте с добавлением собственного свойства stack, строковое значение которого соответствует тому же формату, что и Error.prototype.stack. Это свойство не перечисляется и является настраиваемым. В V8 это пара геттер-сеттер. В SpiderMonkey и JavaScriptCore это свойство данных, которое можно записывать.

Примеры

Использование Error.captureStackTrace()

Утилитарная функция getStack() возвращает текущую трассировку стека в точке вызова, удаляя себя из стека. Это служит той же цели отладки, что и console.trace(), но позволяет выводить строку в другом месте. Обратите внимание, что она не создает экземпляр Error для этой цели, а устанавливает stack для обычного объекта, что было бы более эффективно для наших целей. Обычно вы вызываете Error.captureStackTrace для объектов, предназначенных для выбрасывания в качестве ошибок, как показано в следующем примере.

function getStack() {
  const obj = {};
  if ("captureStackTrace" in Error) {
    // Avoid getStack itself in the stack trace
    Error.captureStackTrace(obj, getStack);
  }
  return obj.stack;
}

function foo() {
  console.log(getStack());
}

foo();
// Error
//     at foo (<anonymous>:8:15)
//     at <anonymous>:11:1

Установка трассировки стека для пользовательского объекта ошибки

Основной сценарий использования Error.captureStackTrace() — установка трассировки стека для пользовательского объекта ошибки. Обычно вы определяете пользовательские ошибки, наследуя от класса Error, что автоматически делает свойство stack доступным через наследование. Однако проблема с трассировкой стека по умолчанию заключается в том, что она включает сам вызов конструктора, что раскрывает детали реализации. Вы можете избежать этого, используя Error.captureStackTrace(), который позволяет установить трассировку стека даже для пользовательских ошибок, не наследуемых от Error.

class MyError extends Error {
  constructor(message, options) {
    super(message, options);
    if ("captureStackTrace" in Error) {
      // Avoid MyError itself in the stack trace
      Error.captureStackTrace(this, MyError);
    }
  }
}

const myError = new MyError("Something went wrong");
console.log(myError.stack);
// Error: Something went wrong
//     at <anonymous>:8:17

Обратите внимание, что даже если вы не вызываете Error.captureStackTrace() здесь, некоторые движки все равно достаточно "умны", чтобы избежать MyError в трассировке стека, если конструктор наследуется от Error. Вызов Error.captureStackTrace() более важен для пользовательских ошибок, которые по какой-либо причине не наследуются от Error.

class MyError {
  constructor(message) {
    this.message = message;
    if ("captureStackTrace" in Error) {
      // Avoid MyError itself in the stack trace
      Error.captureStackTrace(this, MyError);
    }
  }
}

const myError = new MyError("Something went wrong");
console.log(myError.stack);
// Error: Something went wrong
//     at <anonymous>:8:17

Спецификации

Совместимость с браузерами

См. также

• Error.prototype.stack
• Error.stackTraceLimit
• API трассировки стека в документации V8