使用 core-js-pure 避免全局污染：模块化库开发的最佳实践

一、为什么模块化库不能使用常规 core-js

在编写业务终端应用（Application）时，引入 core-js 通常是最省心的方式。开发者在应用入口直接执行 import 'core-js/stable'，或者借助 @babel/preset-env 配合 useBuiltIns: 'entry'，即可将 ES6+ 的新增对象（如 Promise、Map、Set）和原型链扩展方法（如 Array.prototype.flat、String.prototype.replaceAll）直接挂载至全局上下文 globalThis 与构造函数原型上。

然而，对于通用的 npm 开源库、UI 组件库或 SDK 而言，篡改全局对象是极具破坏性的反模式：

• 版本冲突与行为覆盖：宿主应用可能依赖特定版本的标准实现或自制 Polyfill，库注入的 Polyfill 可能因实现细节差异引发宿主应用的逻辑崩溃。
• 原型链污染（Prototype Pollution）：直接向 Array.prototype 或 Object.prototype 扩展非标准属性或提案阶段 API，极易引发不可预期的枚举遍历异常或命名命名碰撞。
• 卸载困难与不可逆性：一旦第三方库执行了全局覆盖代码，宿主应用无法仅针对该模块回滚原型修改，导致整个生命周期内全局环境处于非受控状态。

为了在提供现代化 API 兼容的同时彻底杜绝全局副作用，core-js-pure 应运而生。它是 core-js 的非全局污染版本，所有对标准对象与方法的补丁都作为独立模块导出，既不碰触 window / globalThis，也不修改任何内置对象的原型。

二、现代库开发的标准落地实施步骤

在实际项目工程中，我们不需要手动一条条编写类似 import Promise from 'core-js-pure/actual/promise' 的冗长语句。业界标准做法是结合 Babel 工具链的 @babel/plugin-transform-runtime，在编译打包阶段将代码中的 ES6+ 特性调用自动重写为对 @babel/runtime-corejs3（其底层正是使用 core-js-pure）的导入引用。

步骤一：明确依赖分类与精准安装

在进行库工程初始化时，务必分清开发依赖（devDependencies）与生产依赖（dependencies）。编译插件应置于开发依赖，而运行时实际调用的垫片库则必须列入生产依赖，确保宿主应用在安装该库时能正确拉取对应模块。

# 1. 安装开发构建插件（放置于 devDependencies）
npm install --save-dev @babel/core @babel/preset-env @babel/plugin-transform-runtime

# 2. 安装运行时纯净 Polyfill（放置于 dependencies）
npm install --save @babel/runtime-corejs3

依赖关系说明：@babel/runtime-corejs3 内部通过 package.json 声明直接依赖了 core-js-pure。因此，我们只需要将 @babel/runtime-corejs3 添加至 dependencies 即可，Babel 会负责精准解析。

步骤二：配置 Babel 转换规则

在库项目的根目录下创建 babel.config.json。必须特别注意：在使用 @babel/preset-env 时，不能开启 useBuiltIns: 'usage' 或 useBuiltIns: 'entry'，因为那套逻辑是为整包全局 Polyfill 设计的；应将 Polyfill 职责完全交由 @babel/plugin-transform-runtime 处理。

{
  "presets": [
    [
      "@babel/preset-env",
      {
        "modules": false
      }
    ]
  ],
  "plugins": [
    [
      "@babel/plugin-transform-runtime",
      {
        "corejs": {
          "version": 3,
          "proposals": true
        },
        "helpers": true,
        "regenerator": true
      }
    ]
  ]
}

步骤三：打包工具（Rollup / Vite）外部化声明

开发通用的 npm 库时，切忌将 @babel/runtime-corejs3 内部代码硬打包塞进最终的 bundle 文件中。如果每个第三方库都将 runtime 完整打入产物，不仅会导致最终用户下载体积暴增，还会丢失模块复用优化。

以常见的 rollup.config.mjs 为例，必须通过 external 字段将运行时标记为外部依赖：

import { babel } from '@rollup/plugin-babel';
import resolve from '@rollup/plugin-node-resolve';

export default {
  input: 'src/index.js',
  output: [
    {
      file: 'dist/index.cjs.js',
      format: 'cjs',
      exports: 'named'
    },
    {
      file: 'dist/index.esm.js',
      format: 'esm'
    }
  ],
  // 关键：将所有 @babel/runtime-corejs3 路径标记为 external
  external: [
    /@babel\/runtime-corejs3/
  ],
  plugins: [
    resolve(),
    babel({
      babelHelpers: 'runtime',
      exclude: 'node_modules/**'
    })
  ]
};

三、核心机制：原型方法虚拟化（Virtualization）

在 JavaScript 中，诸如 Promise、Map 这种属于静态对象或构造器，替换非常直观：只需将代码中的标识符 Promise 重命名为导入的 _Promise 即可。但像 [].includes() 或 arr.flat() 这种实例原型方法，如何在不向 Array.prototype 写入任何函数的情况下实现降级调用呢？

这就是 core-js-pure 的核心绝技——原型方法虚拟化。当 Babel 检测到实例调用时，会将其解构为一个独立的辅助函数，并将被调用的实例作为 this 或第一个参数传入。

观察转译后的代码细节：_includesInstanceProperty 是一个来自 @babel/runtime-corejs3 的内部闭包函数。它首先检查当前 items 原型链上是否存在原生的 includes 方法；如果浏览器原生支持，则直接执行原生方法；如果运行在 IE11 或老旧宿主环境中，则调用 core-js-pure/actual/instance/includes 模块内部实现的纯函数进行计算。无论在哪种运行环境，都没有对 Array.prototype 赋予任何新属性。

四、直接模块化调用：无编译步骤的轻量方案

如果开发的是微型工具库（例如只有几十行代码的辅助函数），引入全套 Babel 转译链路可能会略显沉重。此时，我们也可以直接在代码中按需引入 core-js-pure 的特定功能点：

// 示例：在纯原生模块中局部引入特定垫片
import Promise from 'core-js-pure/actual/promise';
import ObjectHasOwn from 'core-js-pure/actual/object/has-own';
import map from 'core-js-pure/actual/array/map';

export function processRecords(records, key) {
  return new Promise((resolve) => {
    // 使用纯净的 Object.hasOwn 模块
    const filtered = records.filter(item => ObjectHasOwn(item, key));
    
    // 使用纯函数风格调用 Array 原型函数
    const result = map(filtered, item => item[key]);
    resolve(result);
  });
}

这种手动导入方式透明度最高，完全由作者控制引入的模块边界，且打包产物体积最为精简。缺点是要求团队对 core-js-pure 提供的路径命名规范（如 /actual/、/features/）有准确的认知。

五、如何编写自动化测试验证零全局污染

为了确信发布的库真正达成了“无全局污染”的质量承诺，建议在 CI 流程中加入专门的污染检测单元测试。我们可以利用 Node.js 干净的进程环境，在 import 或 require 库之前对全局环境进行属性快照，加载后再核对差异：

// test/pollution.test.js
import test from 'node:test';
import assert from 'node:assert/strict';

test('验证库载入后全局环境与原型链零修改', async () => {
  // 1. 记录初始原型链属性集合
  const arrayProtoKeysBefore = Object.getOwnPropertyNames(Array.prototype);
  const globalKeysBefore = Object.getOwnPropertyNames(globalThis);
  
  // 模拟一个老旧环境中未定义的新特性（例如模拟缺失 flat）
  const originalFlat = Array.prototype.flat;
  delete Array.prototype.flat;

  // 2. 动态加载打包后的库产物
  const myLibrary = await import('../dist/index.esm.js');
  
  // 3. 执行一次业务调用
  assert.ok(myLibrary);

  // 4. 严苛断言：Array.prototype 依然不应存在 flat 方法
  assert.equal(Array.prototype.flat, undefined, '错误：库内部执行了全局原型污染！');
  
  // 5. 比对全局对象集合是否有新增键
  const globalKeysAfter = Object.getOwnPropertyNames(globalThis);
  assert.deepEqual(globalKeysBefore, globalKeysAfter, '错误：检测到 globalThis 上存在泄露的全局属性');

  // 还原环境
  Array.prototype.flat = originalFlat;
});

将上述检查作为构建测试的必经节点，可以在代码合入前彻底阻断任何无意间引入的全局 Polyfill 污染。

六、总结与库发布检查清单

在前端模块化日益成熟的当下，评估一个第三方开源库的工程水准，除了看其功能与执行性能外，更要看其对宿主环境的敬畏与尊重。

通过遵循上述工程实践，你可以放心在现代类库中使用 ES 新语法，同时确保所有下游使用者无论处于何种复杂架构中，都能平滑无缝地引入你的模块。