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


  • warning <string> | <Error> 触发的警告。
  • type <string>warning 是一个 String 时,则 type 是用于被触发的警告类型的名称。 默认值: 'Warning'
  • code <string> 要触发的警告实例的唯一标识符。
  • ctor <Function>warning 是一个 String 时,则 ctor 是一个可选的函数,用于限制生成的堆栈信息。默认值: process.emitWarning

process.emitWarning() 方法可用于触发自定义或应用特定的进程警告。 可以通过给 'warning' 事件增加句柄来监听这些警告。

// 使用字符串触发警告。
process.emitWarning('出错啦');
// 触发: (node: 56338) Warning: 出错啦
// 使用字符串和类型触发警告。
process.emitWarning('出错啦', 'CustomWarning');
// 触发: (node:56338) CustomWarning: 出错啦
process.emitWarning('出错啦', 'CustomWarning', 'WARN001');
// 触发: (node:56338) [WARN001] CustomWarning: 出错啦

在前面的每个示例中, process.emitWarning() 内部生成了一个 Error 对象,并传给 'warning' 句柄。

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

如果 warning 是一个 Error 对象,则它将会被透传给 'warning' 事件句柄(并且将会忽略可选的 typecodector 参数):

// 使用错误对象触发警告。
const myWarning = new Error('出错啦');
// 使用错误名称属性指定类型名称。
myWarning.name = 'CustomWarning';
myWarning.code = 'WARN001';

process.emitWarning(myWarning);
// 触发: (node:56338) [WARN001] CustomWarning: 出错啦

如果 warning 不是一个字符串或 Error,则会抛出 TypeError

当进程警告使用 Error 对象时,进程警告机制并不是常用的错误处理机制的替代方式。

如果警告的 type'DeprecationWarning',则会涉及如下额外的处理:

  • 如果使用 --throw-deprecation 命令行标识,则弃用的警告会作为异常抛出,而不是作为事件被触发。
  • 如果使用--no-deprecation 命令行标识,则弃用的警告会被忽略。
  • 如果使用--trace-deprecation 命令行标识,则弃用的警告及其全部堆栈信息会被打印到 stderr
  • 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.

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.