process.emitWarning(warning[, type[, code]][, ctor])

新增于: v6.0.0
  • warning <string> | <Error> 发出的警告。
  • type <string> 如果 warning 是String, type 是警告类型的名字。 默认值: Warning。
  • code <string> 当前警告的唯一标识符。
  • ctor <Function> 如果warning是String，ctor是可选的function，用于限制生成的堆栈信息。默认process.emitWarning

process.emitWarning()方法可用于发出定制的或应用特定的进程警告。 可以通过给process.on('warning')事件增加处理器，监听这些警告。

// Emit a warning using a string.
process.emitWarning('Something happened!');
// Emits: (node: 56338) Warning: Something happened!

// Emit a warning using a string and a type.
process.emitWarning('Something Happened!', 'CustomWarning');
// Emits: (node:56338) CustomWarning: Something Happened!

process.emitWarning('Something happened!', 'CustomWarning', 'WARN001');
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!

在上面例子中，process.emitWarning()内部生成了一个Error对象，并传递给process.on('warning')事件。

process.on('warning', (warning) => {
  console.warn(warning.name);
  console.warn(warning.message);
  console.warn(warning.code);
  console.warn(warning.stack);
});

如果warning参数值是一个Error对象，它会被透传给process.on('warning')的事件监听器(可选参数值type，code and ctor会被忽略)：

// Emit a warning using an Error object.
const myWarning = new Error('Something happened!');
// Use the Error name property to specify the type name
myWarning.name = 'CustomWarning';
myWarning.code = 'WARN001';

process.emitWarning(myWarning);
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!

如果warning的参数值不是string或Error，会抛出 TypeError。

需要注意的是，使用Error对象做为进程警告，并不是常用的错误处理机制的替代方式。

如果警告type是DeprecationWarning，会涉及如下额外的处理：

  • 如果命令行标识包含--throw-deprecation，deprecation warning会作为异常抛出，而不是作为事件被发出。

  • 如果命令行标识包含--no-deprecation，deprecation warning会被忽略。

  • 如果命令行标识包含--trace-deprecation，deprecation warning及其全部堆栈信息会被打印到stderr。

Added in: v6.0.0
  • warning <string> | <Error> The warning to emit.
  • type <string> When warning is a String, type is the name to use for the type of warning being emitted. Default: 'Warning'.
  • code <string> A unique identifier for the warning instance being emitted.
  • ctor <Function> When warning is a String, ctor is an optional function used to limit the generated stack trace. Default: process.emitWarning.

The process.emitWarning() method can be used to emit custom or application specific process warnings. These can be listened for by adding a handler to the 'warning' event.

// Emit a warning using a string.
process.emitWarning('Something happened!');
// Emits: (node: 56338) Warning: Something happened!

// Emit a warning using a string and a type.
process.emitWarning('Something Happened!', 'CustomWarning');
// Emits: (node:56338) CustomWarning: Something Happened!

process.emitWarning('Something happened!', 'CustomWarning', 'WARN001');
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!

In each of the previous examples, an Error object is generated internally by process.emitWarning() and passed through to the 'warning' handler.

process.on('warning', (warning) => {
  console.warn(warning.name);
  console.warn(warning.message);
  console.warn(warning.code);
  console.warn(warning.stack);
});

If warning is passed as an Error object, it will be passed through to the 'warning' event handler unmodified (and the optional type, code and ctor arguments will be ignored):

// Emit a warning using an Error object.
const myWarning = new Error('Something happened!');
// Use the Error name property to specify the type name
myWarning.name = 'CustomWarning';
myWarning.code = 'WARN001';

process.emitWarning(myWarning);
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!

A TypeError is thrown if warning is anything other than a string or Error object.

Note that while process warnings use Error objects, the process warning mechanism is not a replacement for normal error handling mechanisms.

The following additional handling is implemented if the warning type is 'DeprecationWarning':

  • If the --throw-deprecation command-line flag is used, the deprecation warning is thrown as an exception rather than being emitted as an event.
  • If the --no-deprecation command-line flag is used, the deprecation warning is suppressed.
  • If the --trace-deprecation command-line flag is used, the deprecation warning is printed to stderr along with the full stack trace.