Node.js util.types.isNativeError用法：跨Realm错误判定与instanceof的本质区别-代码号

一、这个方法的判定依据不是原型链

util.types.isNativeError(value)返回布尔值，判断一个值是否由内置Error构造器（或其子类构造器）产生。官方文档对这一点的表述经过了一次修正：早期文档写的是“是否为内置Error类型的实例”，后来改为“是否由内置Error类型的构造器返回”。措辞变化的背后是判定机制的差异——它检查的是构造器来源，而非原型链上是否存在Error.prototype。

这个区别在两种场景中产生相反的结果，也是理解这个方法的关键。

二、两种场景：instanceof与isNativeError分道扬镳

场景一：跨Realm的错误。

通过vm模块在不同上下文中创建的Error，其构造器来自该上下文的全局环境，而非当前Realm的Error。instanceofError比较的是当前Realm的原型链，因此返回false。isNativeError不依赖原型链比较，它识别构造器来源，返回true。

const vm = require('node:vm');
const { isNativeError } = require('node:util/types');

const context = vm.createContext({});
const crossRealmError = vm.runInContext('new Error("cross realm")', context);

console.log(crossRealmError instanceof Error);  // false
console.log(isNativeError(crossRealmError));    // true

Vercel的Conformance规则文档专门记录了instanceofError在跨Realm场景下的失效问题，并将isNativeError列为Node.js环境中的推荐替代。Worker线程中产生的错误同样属于这种情况：它由worker环境的Error构造，在主线程中instanceof判定失败。

场景二：伪造原型的对象。

Object.create(Error.prototype)或{__proto__:Error.prototype}创建的对象，原型链上确实存在Error.prototype，因此instanceofError返回true。但它并非由Error构造器返回，isNativeError返回false。

AVA测试框架的文档专门列出了这个反直觉案例：其throws()断言使用isNativeError判断被抛出的值是否为错误，Object.create(Error.prototype)会被拒绝，而开发者可能因为instanceof返回true而感到困惑。AVA给出的解法是在断言期望中设置any:true来放开限制。

值	`instanceofError`	`isNativeError`
`newError()`（同Realm）	`true`	`true`
`vm`中创建的Error	`false`	`true`
`Object.create(Error.prototype)`	`true`	`false`
`{name:'Error'}`	`false`	`false`

三、Node.js内部的实际用法：两者并用

Node.js自身在需要判断“某个值是否为错误”时，并不单独依赖其中任何一个。源码中出现的模式是isNativeError(e)||einstanceofError。这个组合覆盖了两类情况：跨Realm的原生错误（isNativeError为真）和伪造原型但instanceof为真的值。单独使用任何一个都会漏掉一类。

这个模式对于业务代码的启示是：如果你的错误判断逻辑需要尽可能覆盖所有“看起来像错误”的值，组合判断比二选一更稳妥。如果只需要识别真正的原生错误实例（例如在断言或错误分类中），isNativeError的严格性反而是优势。

四、示例：三类值的判定对比

以下示例在同一组输入上对比两种判断方式。示例中的code_number为代码号学习编程的标识。

const vm = require('node:vm');
const { isNativeError } = require('node:util/types');

const values = [
  ['直接构造', new Error('direct')],
  ['子类实例', new (class CodeNumberError extends Error {})('subclass')],
  ['跨 Realm', vm.runInNewContext('new Error("realm")')],
  ['伪造原型', Object.create(Error.prototype)],
  ['普通对象', { message: 'fake', name: 'Error' }],
  ['无参数', undefined]
];

for (const [label, value] of values) {
  console.log({
    label,
    instanceof: value instanceof Error,
    isNativeError: isNativeError(value)
  });
}

输出中，子类实例在两种判断下都为true，这是isNativeError文档明确说明的行为：原生错误类型的子类也是原生错误。跨Realm和伪造原型两行则展示了两种判断的分歧点。

五、一个不能忽略的版本信号：Node.js24的弃用

搜索材料中有一条值得认真对待的信息：Node.js24的变更日志中出现了“deprecateutil.isNativeErrorinfavorofError.isError”的条目，GitHubIssue#57961中也讨论了在V813.4（随Node.js24引入）提供Error.isError之后弃用util.types.isNativeError的可能性。

V8的Error.isError提供的是类似的跨Realm判定能力，但它是ECMAScript层面的标准方法，不依赖Node.js的util.types模块。对于新项目或正在进行版本升级的项目，在代码中优先使用Error.isError（如果目标Node.js版本支持）可以减少对Node.js专有API的依赖。对于需要同时支持旧版本Node.js的项目，isNativeError仍然是当前可用的跨Realm判断手段，但应当在代码注释或迁移计划中标注这一弃用信号。

六、测试中的断言策略

在单元测试中，如果需要断言“某个值确实是原生错误”，isNativeError比instanceof更严格，能过滤掉伪造原型的值。但如果被测逻辑可能抛出跨Realm的错误（例如经过vm或worker边界），instanceof会给出假阴性，此时必须使用isNativeError。

一个常见的测试写法是使用assert.throws配合自定义验证函数，在验证函数内部用isNativeError做二次确认：

const assert = require('node:assert');
const { isNativeError } = require('node:util/types');

assert.throws(
  () => { throw vm.runInNewContext('new Error("from vm")'); },
  (err) => isNativeError(err) && err.message === 'from vm'
);

这种写法的价值在于：它不依赖instanceof，因此对跨Realm的测试场景保持有效。

七、常见误区速查

以为isNativeError等价于instanceofError。两者在跨Realm和伪造原型两种场景下结论相反。官方文档专门用两个示例说明这种不等价。

以为子类实例不会被识别。classMyErrorextendsError{}的实例在isNativeError下返回true。子类构造器调用Error构造器创建对象，来源判定通过。

以为Object.create(Error.prototype)会被识别为错误。不会。isNativeError返回false，尽管instanceof返回true。这是AVA断言文档中记录的实际案例。

以为这个方法在所有Node.js版本中行为一致。判定机制本身稳定，但Node.js24已释放弃用信号，长期项目需要关注Error.isError的替代路径。

八、练习与思考

一个从worker_threads的worker.on('error')回调中拿到的错误对象，在主线程中instanceofError返回什么？isNativeError返回什么？这对错误处理中间件的判断逻辑有什么影响？
如果某个库内部使用Object.create(Error.prototype)构造错误对象（而非newError()），isNativeError会拒绝它。在编写一个通用的错误序列化工具时，是否应该使用isNativeError作为唯一判断条件？Node.js内部的组合判断模式给了什么提示？
在Node.js24环境中，Error.isError与util.types.isNativeError对同一组输入（包括跨Realm和伪造原型）的返回值是否一致？如果项目计划在未来两年内升级到Node.js26，现在是否应该开始迁移？

九、延伸阅读与参考文献

Node.js官方文档util.types.isNativeError(value)，nodejs.cn中文镜像，包含跨Realm返回true、伪造原型返回false的官方示例，以及“子类也是原生错误”的说明。https://url.nodejs.cn/api/v25/util/util_types_isnativeerror_value.html

Node.js文档PR#46840“doc: improve documentation for util.types.isNativeError()”，将判定描述从“是否为实例”修正为“是否由构造器返回”，并补充了跨Realm与伪造原型的双向示例，是理解该方法语义的直接材料。https://github.com/nodejs/node/pull/46840

AVA常见坑文档“Error edge cases”，记录Object.create(Error.prototype)被isNativeError拒绝而instanceof返回true的实际案例，以及any:true的解法。https://github.com/avajs/ava/blob/main/docs/08-common-pitfalls.md

Vercel Conformance规则NO_INSTANCEOF_ERROR，说明跨Realm错误导致instanceof失效的问题，并将isNativeError列为Node.js环境中的替代方案，包含Object.prototype.toString的补充判断思路。https://vercel.com/docs/conformance/rules/no_instanceof_error

Deno文档types.isNativeError，提供与Node.js文档一致的跨Realm示例以及子类识别示例，可作为跨运行时行为的交叉参考。https://deno-docs-gyb3y9rg44tb.deno.dev/api/node/util/~/types.isNativeError

Node.js GitHub Issue #57961，讨论随V813.4引入Error.isError后弃用util.types.isNativeError的可能性，包含性能回归（约50%）的讨论，是版本迁移决策的参考材料。https://github.com/nodejs/node/issues/57961

Node.js24变更日志条目，记录“deprecate util.isNativeError in favor of Error.isError”的正式弃用动作。https://mac.softpedia.com/progChangelog/Node-Changelog-100587.html

本文标签：

Node.js util.types.isNativeError用法：跨Realm错误判定与instanceof的本质区别