错误

¥Description

运行时错误会导致创建并抛出新的 Error 对象。

¥Runtime errors result in new Error objects being created and thrown.

Error 是 serializable object，因此可以使用 structuredClone() 进行克隆，或者使用 postMessage() 在 工人 之间进行复制。

¥Error is a serializable object, so it can be cloned with structuredClone() or copied between Workers using postMessage().

¥Error types

除了通用的 Error 构造函数之外，JavaScript 中还有其他核心错误构造函数。对于客户端异常，请参见 异常处理语句。

¥Besides the generic Error constructor, there are other core error constructors in JavaScript. For client-side exceptions, see Exception handling statements.

EvalError

创建一个代表全局函数 eval() 发生的错误的实例。

RangeError

创建一个实例，表示当数值变量或参数超出其有效范围时发生的错误。

ReferenceError

创建一个表示取消引用无效引用时发生的错误的实例。

SyntaxError

创建一个表示语法错误的实例。

TypeError

创建一个实例，表示当变量或参数的类型无效时发生的错误。

URIError

创建一个实例，表示当向 encodeURI() 或 decodeURI() 传递无效参数时发生的错误。

AggregateError

当某个操作（例如 Promise.any()）需要报告多个错误时，创建一个代表多个错误的实例，这些错误包含在一个错误中。

InternalError Non-standard

创建一个代表 JavaScript 引擎中抛出内部错误时发生的错误的实例。例如。"太多的递归"。

¥Constructor

Error()

创建一个新的 Error 对象。

¥Static methods

Error.captureStackTrace() Non-standard

非标准 V8 函数，在 Error 实例上创建 stack 属性。

Error.stackTraceLimit Non-standard

非标准 V8 数值属性，限制错误堆栈跟踪中包含的堆栈帧数量。

Error.prepareStackTrace() Non-standard Optional

非标准 V8 函数，如果由用户代码提供，则由 V8 JavaScript 引擎调用以抛出异常，从而允许用户为堆栈跟踪提供自定义格式。

¥Instance properties

这些属性在 Error.prototype 上定义并由所有 Error 实例共享。

¥These properties are defined on Error.prototype and shared by all Error instances.

Error.prototype.constructor

创建实例对象的构造函数。对于 Error 实例，初始值为 Error 构造函数。

Error.prototype.name

表示错误类型的名称。对于 Error.prototype.name，初始值为 "Error"。像 TypeError 和 SyntaxError 这样的子类提供它们自己的 name 属性。

Error.prototype.stack Non-standard

堆栈跟踪的非标准属性。

这些属性是每个 Error 实例自己的属性。

¥These properties are own properties of each Error instance.

cause

错误原因，指示引发当前错误的原因 - 通常是另一个捕获的错误。对于用户创建的 Error 对象，这是作为构造函数第二个参数的 cause 属性提供的值。

columnNumber Non-standard

引发此错误的行中的列号的非标准 Mozilla 属性。

fileName Non-standard

引发此错误的文件路径的非标准 Mozilla 属性。

lineNumber Non-standard

引发此错误的文件中行号的非标准 Mozilla 属性。

message

错误信息。对于用户创建的 Error 对象，这是作为构造函数的第一个参数提供的字符串。

¥Instance methods

Error.prototype.toString()

返回表示指定对象的字符串。覆盖 Object.prototype.toString() 方法。

¥Examples

¥Throwing a generic error

通常，你创建 Error 对象的目的是使用 throw 关键字引发它。你可以使用 try...catch 构造来处理错误：

¥Usually you create an Error object with the intention of raising it using the throw keyword. You can handle the error using the try...catch construct:

try {
  throw new Error("Whoops!");
} catch (e) {
  console.error(`${e.name}: ${e.message}`);
}

¥Handling a specific error type

你可以通过使用 instanceof 关键字测试错误类型来选择仅处理特定错误类型：

¥You can choose to handle only specific error types by testing the error type with the instanceof keyword:

try {
  foo.bar();
} catch (e) {
  if (e instanceof EvalError) {
    console.error(`${e.name}: ${e.message}`);
  } else if (e instanceof RangeError) {
    console.error(`${e.name}: ${e.message}`);
  }
  // etc.
  else {
    // If none of our cases matched leave the Error unhandled
    throw e;
  }
}

¥Differentiate between similar errors

有时，代码块可能会因需要不同处理的原因而失败，但会引发非常相似的错误（即具有相同的类型和消息）。

¥Sometimes a block of code can fail for reasons that require different handling, but which throw very similar errors (i.e. with the same type and message).

如果你无法控制引发的原始错误，一种选择是捕获它们并引发具有更具体消息的新 Error 对象。原始错误应传递给构造函数的 options 参数中的新 Error 作为其 cause 属性。这确保了原始错误和堆栈跟踪可用于更高级别的 try/catch 块。

¥If you don't have control over the original errors that are thrown, one option is to catch them and throw new Error objects that have more specific messages. The original error should be passed to the new Error in the constructor's options parameter as its cause property. This ensures that the original error and stack trace are available to higher-level try/catch blocks.

下面的示例展示了两种方法，否则它们会因类似错误而失败（doFailSomeWay() 和 doFailAnotherWay()）：

¥The example below shows this for two methods that would otherwise fail with similar errors (doFailSomeWay() and doFailAnotherWay()):

function doWork() {
  try {
    doFailSomeWay();
  } catch (err) {
    throw new Error("Failed in some way", { cause: err });
  }
  try {
    doFailAnotherWay();
  } catch (err) {
    throw new Error("Failed in another way", { cause: err });
  }
}

try {
  doWork();
} catch (err) {
  switch (err.message) {
    case "Failed in some way":
      handleFailSomeWay(err.cause);
      break;
    case "Failed in another way":
      handleFailAnotherWay(err.cause);
      break;
  }
}

注意：如果你正在创建一个库，你应该更喜欢使用错误原因来区分发出的不同错误，而不是要求你的消费者解析错误消息。请参阅 错误原因页面 的示例。

¥Note: If you are making a library, you should prefer to use error cause to discriminate between different errors emitted — rather than asking your consumers to parse the error message. See the error cause page for an example.

自定义错误类型 也可以使用 cause 属性，前提是子类的构造函数在调用 super() 时传递 options 参数。Error() 基类构造函数将读取 options.cause 并在新错误实例上定义 cause 属性。

¥Custom error types can also use the cause property, provided the subclasses' constructor passes the options parameter when calling super(). The Error() base class constructor will read options.cause and define the cause property on the new error instance.

class MyError extends Error {
  constructor(message, options) {
    // Need to pass `options` as the second parameter to install the "cause" property.
    super(message, options);
  }
}

console.log(new MyError("test", { cause: new Error("cause") }).cause);
// Error: cause

¥Custom error types

你可能希望定义自己的从 Error 派生的错误类型，以便能够 throw new MyError() 并使用 instanceof MyError 检查异常处理程序中的错误类型。这会产生更干净、更一致的错误处理代码。

¥You might want to define your own error types deriving from Error to be able to throw new MyError() and use instanceof MyError to check the kind of error in the exception handler. This results in cleaner and more consistent error handling code.

请参阅 StackOverflow 上的 "在 JavaScript 中扩展 Error 的好方法是什么？" 进行深入讨论。

¥See "What's a good way to extend Error in JavaScript?" on StackOverflow for an in-depth discussion.

警告：内置子类无法可靠地转换为 ES6 之前的代码，因为没有办法在没有 Reflect.construct() 的情况下使用特定的 new.target 构造基类。需要 附加配置 或者在构造函数末尾手动调用 Object.setPrototypeOf(this, CustomError.prototype)；否则，构造的实例将不是 CustomError 实例。请参阅 TypeScript 常见问题解答 了解更多信息。

¥Warning: Builtin subclassing cannot be reliably transpiled to pre-ES6 code, because there's no way to construct the base class with a particular new.target without Reflect.construct(). You need additional configuration or manually call Object.setPrototypeOf(this, CustomError.prototype) at the end of the constructor; otherwise, the constructed instance will not be a CustomError instance. See the TypeScript FAQ for more information.

注意：使用 ES2015 类时，某些浏览器在堆栈跟踪中包含 CustomError 构造函数。

¥Note: Some browsers include the CustomError constructor in the stack trace when using ES2015 classes.

class CustomError extends Error {
  constructor(foo = "bar", ...params) {
    // Pass remaining arguments (including vendor specific ones) to parent constructor
    super(...params);

    // Maintains proper stack trace for where our error was thrown (only available on V8)
    if (Error.captureStackTrace) {
      Error.captureStackTrace(this, CustomError);
    }

    this.name = "CustomError";
    // Custom debugging information
    this.foo = foo;
    this.date = new Date();
  }
}

try {
  throw new CustomError("baz", "bazMessage");
} catch (e) {
  console.error(e.name); // CustomError
  console.error(e.foo); // baz
  console.error(e.message); // bazMessage
  console.error(e.stack); // stacktrace
}

¥See also

• Error 的 Polyfill，在 core-js 中支持 cause
• throw
• try...catch
• V8 文档中的 堆栈跟踪 API