util.deprecate(fn, msg[, code])

• fn <Function> 正在被弃用的函数。
• msg <string> 当调用已弃用的函数时显示的警告信息。
• code <string> 一个弃用代码。有关代码列表，请参阅 已弃用的 API 列表。
• 返回值：<Function> 已弃用的函数，会发出警告。

util.deprecate() 方法会封装 fn（它可以是函数或类），从而将其标记为已废弃。

【The util.deprecate() method wraps fn (which may be a function or class) in such a way that it is marked as deprecated.】

import { deprecate } from 'node:util';

export const obsoleteFunction = deprecate(() => {
  // Do something here.
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');const { deprecate } = require('node:util');

exports.obsoleteFunction = deprecate(() => {
  // Do something here.
}, 'obsoleteFunction() is deprecated. Use newShinyFunction() instead.');拷贝

当被调用时，util.deprecate() 将返回一个函数，该函数会使用 'warning' 事件发出 DeprecationWarning（弃用警告）。该警告将在返回的函数第一次被调用时发出，并打印到 stderr。在警告发出之后，被封装的函数将被调用而不会再次发出警告。

【When called, util.deprecate() will return a function that will emit a DeprecationWarning using the 'warning' event. The warning will be emitted and printed to stderr the first time the returned function is called. After the warning is emitted, the wrapped function is called without emitting a warning.】

如果在多次调用 util.deprecate() 时提供了相同的可选 code，针对该 code 的警告只会发出一次。

【If the same optional code is supplied in multiple calls to util.deprecate(), the warning will be emitted only once for that code.】

import { deprecate } from 'node:util';

const fn1 = deprecate(
  () => 'a value',
  'deprecation message',
  'DEP0001',
);
const fn2 = deprecate(
  () => 'a  different value',
  'other dep message',
  'DEP0001',
);
fn1(); // Emits a deprecation warning with code DEP0001
fn2(); // Does not emit a deprecation warning because it has the same codeconst { deprecate } = require('node:util');

const fn1 = deprecate(
  function() {
    return 'a value';
  },
  'deprecation message',
  'DEP0001',
);
const fn2 = deprecate(
  function() {
    return 'a  different value';
  },
  'other dep message',
  'DEP0001',
);
fn1(); // Emits a deprecation warning with code DEP0001
fn2(); // Does not emit a deprecation warning because it has the same code拷贝

如果使用了 --no-deprecation 或 --no-warnings 命令行标志，或者在第一次弃用警告之前将 process.noDeprecation 属性设置为 true，util.deprecate() 方法将不会执行任何操作。

【If either the --no-deprecation or --no-warnings command-line flags are used, or if the process.noDeprecation property is set to true prior to the first deprecation warning, the util.deprecate() method does nothing.】

如果设置了 --trace-deprecation 或 --trace-warnings 命令行标志，或 process.traceDeprecation 属性设置为 true，第一次调用已弃用的函数时，会将警告和堆栈跟踪打印到 stderr。

【If the --trace-deprecation or --trace-warnings command-line flags are set, or the process.traceDeprecation property is set to true, a warning and a stack trace are printed to stderr the first time the deprecated function is called.】

如果设置了 --throw-deprecation 命令行标志，或者将 process.throwDeprecation 属性设置为 true，则在调用已弃用的函数时将抛出异常。

【If the --throw-deprecation command-line flag is set, or the process.throwDeprecation property is set to true, then an exception will be thrown when the deprecated function is called.】

--throw-deprecation 命令行标志和 process.throwDeprecation 属性优先于 --trace-deprecation 和 process.traceDeprecation。

【The --throw-deprecation command-line flag and process.throwDeprecation property take precedence over --trace-deprecation and process.traceDeprecation.】