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

新增于: v6.0.0

warning <string> | <Error> 要触发的警告。
type <string> 当 warning 是 String 时，type 是用于触发警告的 type 的名称。 默认值: 'Warning'。
code <string> 触发的警告实例的唯一标识符。
ctor <Function> 当 warning 为 String 时，ctor 是可选函数，用于限制生成的堆栈跟踪。 默认值: process.emitWarning。

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

import { emitWarning } from 'node:process';

// 使用字符串触发警告。
emitWarning('Something happened!');
// 触发: (node: 56338) Warning: Something happened!const { emitWarning } = require('node:process');

// 使用字符串触发警告。
emitWarning('Something happened!');
// 触发: (node: 56338) Warning: Something happened!

import { emitWarning } from 'node:process';

// 使用字符串和类型触发警告。
emitWarning('Something Happened!', 'CustomWarning');
// 触发: (node:56338) CustomWarning: Something Happened!const { emitWarning } = require('node:process');

// 使用字符串和类型触发警告。
emitWarning('Something Happened!', 'CustomWarning');
// 触发: (node:56338) CustomWarning: Something Happened!

import { emitWarning } from 'node:process';

emitWarning('Something happened!', 'CustomWarning', 'WARN001');
// 触发: (node:56338) [WARN001] CustomWarning: Something happened!const { emitWarning } = require('node:process');

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

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

import process from 'node:process';

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

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

如果 warning 作为 Error 对象传入，则它将被不加修改地传给 'warning' 事件句柄（并且可选的 type、code 和 ctor 参数将被忽略）：

import { emitWarning } from 'node:process';

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

emitWarning(myWarning);
// 触发: (node:56338) [WARN001] CustomWarning: Something happened!const { emitWarning } = require('node:process');

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

emitWarning(myWarning);
// 触发: (node:56338) [WARN001] CustomWarning: Something happened!

如果 warning 不是字符串或 Error 对象，则抛出 TypeError。

虽然进程警告使用 Error 对象，但进程警告机制不是替代正常错误处理机制。

如果警告 type 为 'DeprecationWarning'，则执行以下额外处理：

如果使用 --throw-deprecation 命令行标志，则弃用警告将作为异常抛出，而不是作为事件触发。
如果使用 --no-deprecation 命令行标志，则会取消弃用警告。
如果使用 --trace-deprecation 命令行标志，则弃用警告将与完整堆栈跟踪一起打印到 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.

import { emitWarning } from 'node:process';

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

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

import { emitWarning } from 'node:process';

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

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

import { emitWarning } from 'node:process';

emitWarning('Something happened!', 'CustomWarning', 'WARN001');
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!const { emitWarning } = require('node:process');

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.

import process from 'node:process';

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

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):

import { emitWarning } from 'node:process';

// 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';

emitWarning(myWarning);
// Emits: (node:56338) [WARN001] CustomWarning: Something happened!const { emitWarning } = require('node:process');

// 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';

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.