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'
事件句柄(并且将会忽略可选的 type
、 code
和 ctor
参数):
// 使用错误对象触发警告。
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> Whenwarning
is aString
,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> Whenwarning
is aString
,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 tostderr
along with the full stack trace.