es-toolkit `isNative` 完全指南：识别 JavaScript 引擎原生函数的原理与实战-育师

es-toolkit`isNative`完全指南：识别 JavaScript 引擎原生函数的原理与实战

【免费下载链接】es-toolkitA modern JavaScript utility library that's 2-3 times faster and up to 97% smaller, a major upgrade to lodash.项目地址: https://gitcode.com/GitHub_Trending/es/es-toolkit

本文围绕 es-toolkit 兼容层（es-toolkit/compat）中的isNative函数展开，讲解如何判断一个值是否为 JavaScript 引擎（浏览器或 Node.js）实现的原生函数，并深入剖析其底层基于Function.prototype.toString的正则检测原理、core-js 防御机制与边界行为。读完本文，你将掌握isNative的完整用法、判断边界（绑定函数、伪装函数、非函数值）以及 lodash 兼容场景下的迁移注意事项。

isNative是 es-toolkit 为了与 lodash 保持 1:1 兼容而提供的谓词函数（predicate），主要用于区分引擎内置函数与用户自定义函数、库函数。与 es-toolkit 严格 API（es-toolkit）不同，isNative只存在于兼容入口 src/compat/predicate/isNative.ts，并从 src/compat/compat.ts#L205 统一导出。

函数签名与返回值

const result = isNative(value);

参数：value（any）——要检查的值。
返回值：boolean——如果值看起来是原生函数则返回true，否则返回false。

从源码看，isNative的类型签名是一个类型谓词（type guard）：

export function isNative(value: any): value is (...args: any[]) => any { if (typeof value !== 'function') { return false; } ... }

也就是说，当isNative(value)返回true时，TypeScript 会在后续代码中把value收窄为(...args: any[]) => any的可调用函数类型，方便你安全地直接调用它。

基本用法

isNative的典型使用场景是区分浏览器或 Node.js 提供的内置函数与用户自己定义的函数：

import { isNative } from 'es-toolkit/compat'; // 原生函数 isNative(Array.prototype.push); // true isNative(Object.keys); // true isNative(Math.max); // true isNative(JSON.parse); // true isNative(console.log); // true (在浏览器/Node.js 环境中) // 用户定义函数 isNative(function () {}); // false isNative(() => {}); // false isNative(function customFunction() {}); // false // 库函数 isNative(require('lodash').map); // false isNative(require('es-toolkit').chunk); // false // 非函数值 isNative({}); // false isNative([]); // false isNative('function'); // false isNative(123); // false isNative(null); // false // 绑定函数 const boundFunction = Array.prototype.push.bind([]); isNative(boundFunction); // true (绑定函数是原生的) // 方法 const obj = { method: Array.prototype.push }; isNative(obj.method); // true (仍然是原生函数)

注意两个容易踩坑的边界：绑定函数（Function.prototype.bind的产物）的toString结果仍保留[native code]标记，因此被判定为原生；而对象上引用的原生方法，无论从哪个对象取出，其函数本身仍是原生函数。

底层实现原理：基于`Function.prototype.toString`的正则检测

isNative的检测思路非常经典：原生函数在调用Function.prototype.toString时，其字符串表示中必然包含[native code]标记。核心实现位于 src/compat/predicate/isNative.ts：

const functionToString = Function.prototype.toString; // 用于转义正则语法字符 const REGEXP_SYNTAX_CHARS = /[\\^$.*+?()[\]{}|]/g; // 以 Object.prototype.hasOwnProperty 的 toString 结果为模板构造检测正则 const IS_NATIVE_FUNCTION_REGEXP = RegExp( `^${functionToString .call(Object.prototype.hasOwnProperty) .replace(REGEXP_SYNTAX_CHARS, '\\$&') .replace(/hasOwnProperty|(function).*?(?=\\\()| for .+?(?=\\\])/g, '$1.*?')}$` ); export function isNative(value: any): value is (...args: any[]) => any { if (typeof value !== 'function') { return false; } if ((globalThis as any)?.['__core-js_shared__'] != null) { throw new Error('Unsupported core-js use. Try https://npms.io/search?q=ponyfill.'); } return IS_NATIVE_FUNCTION_REGEXP.test(functionToString.call(value)); }

整个流程分三步：

类型预检：先通过typeof value !== 'function'快速过滤掉所有非函数值，这一步让isNative({})、isNative([])、isNative('function')、isNative(123)、isNative(null)直接返回false，无需进入字符串匹配。
构造检测正则：取一个公认的原生函数Object.prototype.hasOwnProperty，调用Function.prototype.toString得到类似function hasOwnProperty() { [native code] }的字符串，先用REGEXP_SYNTAX_CHARS转义其中可能破坏正则语法的字符，再把函数名（hasOwnProperty）、参数列表（(function).*?(?=\()）以及for ...后缀替换为通配.*?，最终生成一个能匹配任意原生函数toString输出的正则。
正则匹配：对目标值同样调用Function.prototype.toString（注意必须用functionToString.call(value)而非value.toString()，避免函数被重写过toString），与上述正则进行匹配。

这种“用原生函数自证”的方式非常巧妙：检测模板本身取自引擎真实输出的原生函数字符串，因此对 V8、JavaScriptCore、SpiderMonkey 等不同引擎在格式上的细微差异都有一定容忍度。

core-js 检测与防御机制

源码中有一段对很多开发者来说比较陌生的逻辑：

if ((globalThis as any)?.['__core-js_shared__'] != null) { throw new Error('Unsupported core-js use. Try https://npms.io/search?q=ponyfill.'); }

core-js 这类 polyfill 库会通过__core-js_shared__暴露内部共享状态，并用“伪装成原生函数”的方式替换内置 API。如果环境中存在该标记，isNative的正则检测结果将不可信，因此 es-toolkit 选择直接抛出错误而非返回错误结果。这一行为在 src/compat/predicate/isNative.spec.ts#L87-L97 中有对应测试：临时在globalThis上挂载__core-js_shared__后调用isNative(noop)即抛出异常，测试结束后再删除该属性还原环境。

这提醒使用者：如果在 polyfill 环境（尤其是 core-js）中调用isNative，请先确认该环境是否会污染__core-js_shared__，否则会收到显式抛出的错误。

边界行为与测试验证

仓库中的测试用例 src/compat/predicate/isNative.spec.ts 直接沿用了 lodash 的测试集（文件头注释注明参考了 lodash 的isNative.spec.js），覆盖了以下几类边界：

返回true的原生函数：Array、Promise、Uint8Array、Object.keys、Array.prototype.push、Function.prototype.bind、String.prototype.charAt、Number.prototype.toFixed、Math.max、Object.create、encodeURI、Array.prototype.slice等。

返回false的值：undefined、null、布尔值、数字、字符串、对象、数组、箭头函数、普通函数声明、Date、Error、正则、Symbol、Map、Set、WeakMap、WeakSet、ArrayBuffer、DataView等。

伪装成原生的函数：测试还构造了一个重写toString返回'function () { [native code] }'的假原生函数：

const fakeNative = () => {}; Object.defineProperty(fakeNative, 'toString', { value: () => 'function () { [native code] }', }); expect(isNative(fakeNative)).toBe(false);

由于实现中统一使用缓存的Function.prototype.toString进行检测，而非调用目标对象自身的toString，因此这种伪造手法无法骗过isNative，返回结果依然是false。这也是实现中单独缓存const functionToString = Function.prototype.toString的原因之一。

性能对比与基准测试

仓库在 benchmarks/performance/isNative.bench.ts 中提供了与 lodash 的同名函数进行对照的基准测试，测试负载同时覆盖原生函数（Array.prototype.push、Object.keys、Math.max、Promise、Uint8Array）和非原生值（undefined、null、{}、[]、箭头函数）。基准测试基于 vitest 的bench能力运行，可参考 vitest.config.mts 了解基准环境的配置方式，在本地复现 es-toolkit 与 lodash 在该场景下的性能差异。

与 es-toolkit 严格 API 的关系

需要说明的是，isNative仅存在于 lodash 兼容入口es-toolkit/compat，并未出现在 es-toolkit 严格 API（src/predicate目录下搜索不到该函数）。这与 docs/compat/intro.md 中描述的兼容层定位一致：es-toolkit/compat以 1:1 的方式镜像 lodash 的接口与行为，用于让既有 lodash 代码库无需改写调用点即可迁移；而严格 API 只暴露类型安全、现代化的形式。因此，如果你的项目并未使用 lodash，官方建议直接使用es-toolkit严格入口，isNative这类兼容专用函数仅在迁移 lodash 代码时才有必要引入。

小结

isNative是一个实现精巧的引擎能力检测工具：它利用原生函数toString输出中的[native code]标记，以Object.prototype.hasOwnProperty的字符串输出为模板动态构造检测正则，并通过缓存Function.prototype.toString、跳过非函数值、防御 core-js 污染等方式保证结果的可靠性。结合源码实现、测试用例与基准测试，你可以在需要区分引擎内置函数与自定义函数的场景中放心使用，并理解其在 polyfill 环境下的行为限制。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考