core-js 3 模块化标准库实战：ECMAScript 2026 特性按需引入与无污染方案

本文以仓库 packages/core-js/README.md 为主体，系统讲解 core-js 这一模块化 JavaScript 标准库的定位、入口结构与三种典型引入方式：全局一次性引入、按需精准加载、以及通过 core-js-pure 实现零全局命名空间污染。读完本文，你将掌握 core-js 的目录组织（actual/stable/stage/web/modules 等）、运行时配置项（configurator.js）以及如何依据仓库源码与测试用例验证各类特性（如 Promise.try、Set.prototype.union、Iterator 组合操作、structuredClone）的真实行为。

一、core-js 是什么：一个模块化的 JavaScript 标准库

core-js 的官方自我定位是 modular standard library for JavaScript（模块化 JavaScript 标准库）。它并非简单的"补丁集合"，而是覆盖了从 ECMAScript 规范到跨平台 Web 标准的一整套实现，主要包括：

• ECMAScript 已定稿特性（截至 2026）：promises、symbols、collections（Map/Set/WeakMap/WeakSet）、iterators、typed arrays 以及大量其他特性；
• ECMAScript 提案（Proposals）：处于不同 Stage 阶段的实验性 API；
• 跨平台 WHATWG / W3C 特性与提案：例如 URL 与 URLSearchParams、structuredClone、queueMicrotask、setImmediate 等。

这些能力在仓库中的目录上得到了直接印证。以 packages/core-js 包为例，其入口文件 index.js 只有两行：

'use strict';
module.exports = require('./full');

即安装 core-js 后默认导出的是 full 全量目录。而 actual/index.js 则展示了另一条聚合链：

'use strict';
require('../stable');
require('../stage/3');

module.exports = require('../internals/path');

可以看到 actual 集合 = 已定稿的 stable 特性 + Stage 3 提案。类似地，web/index.js 通过逐个 require 聚合了 web.atob、web.btoa、web.dom-collections.for-each、web.structured-clone、web.url、web.queue-microtask、web.timers 等 Web 标准模块，最终同样返回 ../internals/path 作为统一命名空间入口。

二、安装与包入口

在 Node.js / 前端项目中安装：

npm install core-js

仓库中的 package.json 记录了当前包的元信息（版本 3.50.0，main 指向 index.js，type 为 commonjs，sideEffects: true，并带有 postinstall 脚本）。sideEffects: true 意味着该包被设计为在导入时立即产生副作用（即向全局对象挂载 polyfill），这与"引入即生效"的使用方式一致。

针对不同引入需求，仓库还提供了另外两个配套包：core-js-pure（无全局污染版本，见下文第三节）与 core-js-builder、core-js-bundle、core-js-compat（分别用于定制构建、打包分发与目标环境兼容性计算）。

三、三种引入方式（原文档核心示例，完整可运行）

3.1 全局版本：一次性引入全部特性

最直接的方式是整体引入 core-js/actual，它会将 ES 已定稿特性与 Stage 3 提案全部注入全局环境：

import 'core-js/actual';

Promise.try(() => 42).then(it => console.log(it)); // => 42

Array.from(new Set([1, 2, 3]).union(new Set([3, 4, 5]))); // => [1, 2, 3, 4, 5]

[1, 2].flatMap(it => [it, it]); // => [1, 1, 2, 2]

Iterator.concat([1, 2], function * (i) { while (true) yield i++; }(3))
  .drop(1).take(5)
  .filter(it => it % 2)
  .map(it => it ** 2)
  .toArray(); // => [9, 25]

structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])

这段示例覆盖了四类典型能力：

• Promise.try（静态方法，来自提案）；
• Set.prototype.union 与 Array.from（集合运算 + 静态方法）；
• Array.prototype.flatMap（ES2019 定稿特性）；
• Iterator 协议族的组合操作：concat、drop、take、filter、map、toArray——对两个迭代器（第二个是无限生成器）做流水线式处理，最终得到 [9, 25]；
• structuredClone（Web 标准，深克隆任意可结构化克隆对象，此处克隆 Set）。

以上行为均可在仓库测试中看到对应用例，例如 tests/unit-global/es.promise.try.js、tests/unit-global/es.set.union.js、tests/unit-global/es.iterator.concat.js 与 tests/unit-global/web.structured-clone.js。

3.2 按需加载：只引入用到的模块

全局引入虽方便，但会带入全部代码。core-js 的模块化设计允许你针对单个特性精确引入，大幅压缩打包体积：

import 'core-js/actual/promise';
import 'core-js/actual/set';
import 'core-js/actual/iterator';
import 'core-js/actual/array/from';
import 'core-js/actual/array/flat-map';
import 'core-js/actual/structured-clone';

Promise.try(() => 42).then(it => console.log(it)); // => 42

Array.from(new Set([1, 2, 3]).union(new Set([3, 4, 5]))); // => [1, 2, 3, 4, 5]

[1, 2].flatMap(it => [it, it]); // => [1, 1, 2, 2]

Iterator.concat([1, 2], function * (i) { while (true) yield i++; }(3))
  .drop(1).take(5)
  .filter(it => it % 2)
  .map(it => it ** 2)
  .toArray(); // => [9, 25]

structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])

与 3.1 相比，业务代码完全不变，只是把一条 import 'core-js/actual' 拆成了六条细分导入。从仓库目录看，actual/ 下的每个子目录/文件都对应一类或一个特性，例如 actual/promise/、actual/set/、actual/iterator/、actual/array/from.js、actual/array/flat-map.js、actual/structured-clone.js，一一对应，方便你按实际使用面裁剪。

3.3 无全局污染：core-js-pure（Ponyfill 风格）

有些场景不允许修改全局对象（如库/框架开发、SDK 集成、严格隔离的宿主环境）。这时应使用 core-js-pure，它以导入即返回函数/构造器的方式工作，不触碰全局命名空间：

import Promise from 'core-js-pure/actual/promise';
import Set from 'core-js-pure/actual/set';
import Iterator from 'core-js-pure/actual/iterator';
import from from 'core-js-pure/actual/array/from';
import flatMap from 'core-js-pure/actual/array/flat-map';
import structuredClone from 'core-js-pure/actual/structured-clone';

Promise.try(() => 42).then(it => console.log(it)); // => 42

from(new Set([1, 2, 3]).union(new Set([3, 4, 5]))); // => [1, 2, 3, 4, 5]

flatMap([1, 2], it => [it, it]); // => [1, 1, 2, 2]

Iterator.concat([1, 2], function * (i) { while (true) yield i++; }(3))
  .drop(1).take(5)
  .filter(it => it % 2)
  .map(it => it ** 2)
  .toArray(); // => [9, 25]

structuredClone(new Set([1, 2, 3])); // => new Set([1, 2, 3])

注意这里的调用差异：由于是纯函数/纯构造器，Array.from 变成显式的 from(array, ...) 调用，flatMap 变成 flatMap(array, fn) 调用，Promise、Set、Iterator、structuredClone 则以具名导入的方式使用。该方案的具体说明见 packages/core-js-pure/README.md。

三种方式的选择建议：追求零配置、快速上手选 3.1；关心打包体积且环境可控选 3.2；开发可复用库、必须保证宿主环境不被污染选 3.3。

四、入口目录体系：actual / es / stable / full / proposals / stage / web

从源码目录可以清晰看出 core-js 的分层设计（均在 packages/core-js 下）：

目录	语义	依据
actual/	当前推荐入口：stable + Stage 3	actual/index.js
es/	仅已定稿 ECMAScript 特性	目录中的 es.* 模块
stable/	已定稿特性（ES + 部分 Web）	目录结构
full/	全量聚合入口	index.js 指向 ./full
proposals/	全部提案特性（包含 Stage 0 起各阶段）	proposals/index.js，其注释注明计划在 core-js@4 移除该入口
stage/	按提案阶段分目录（stage/0～stage/4 语义）	stage/index.js 聚合 ./pre
web/	WHATWG / W3C 标准特性	web/index.js
modules/	每个特性的底层实现模块（web.*、es.* 等）	modules
internals/	内部工具与共享命名空间（path 等）	actual/index.js 中的引用

引用级别粒度同样精细：如 es.array.flat-map、es.promise.try、web.structured-clone、web.url 等模块文件都真实存在于 packages/core-js/modules 下，并且都有对应的单元测试，例如 tests/unit-global/web.url.js、tests/unit-global/es.array.flat-map.js。你可以依据"模块名 = 特性名"的规律，快速在仓库中定位任何特性的实现与测试。

五、运行时配置：configurator.js 与引入方式

除了在 import 层面做选择，core-js 还提供了运行时配置入口 configurator.js，用于控制 polyfill 的"激进程度"（aggressiveness level）：

module.exports = function (options) {
  if (options && typeof options == 'object') {
    setAggressivenessLevel(options.useNative, isForced.NATIVE);
    setAggressivenessLevel(options.usePolyfill, isForced.POLYFILL);
    setAggressivenessLevel(options.useFeatureDetection, null);
    if (hasOwn(options, USE_FUNCTION_CONSTRUCTOR)) {
      shared[USE_FUNCTION_CONSTRUCTOR] = !!options[USE_FUNCTION_CONSTRUCTOR];
    }
    if (hasOwn(options, ASYNC_ITERATOR_PROTOTYPE)) {
      shared[ASYNC_ITERATOR_PROTOTYPE] = options[ASYNC_ITERATOR_PROTOTYPE];
    }
  }
};

从源码可提取出以下配置项的语义：

• useNative（数组）：指定这些特性始终使用宿主原生实现，不做 polyfill（对应内部常量 isForced.NATIVE）；
• usePolyfill（数组）：指定这些特性强制使用 polyfill，即使宿主原生支持（对应 isForced.POLYFILL）；
• useFeatureDetection（数组）：对这些特性启用特性检测逻辑（对应置 null，即按检测结果决定）；
• USE_FUNCTION_CONSTRUCTOR（布尔）：控制是否允许使用 Function 构造函数（某些极端环境禁用它）；
• AsyncIteratorPrototype：指定异步迭代器原型对象，用于自定义 AsyncIterator 的环境。

需要说明的是，configurator.js 面向高级定制场景，绝大多数项目并不需要调用它；它把"按特性粒度强制 native/polyfill"的能力暴露给上层构建工具（如 core-js-builder）使用。

六、仓库内的验证路径与延伸阅读

如果你想亲自验证本文所述行为，可以直接运行仓库自带测试。以 Node.js 为例：

# 在仓库根目录运行全局版本单元测试
npm test -- --modules es.promise.try,es.set.union,es.iterator.concat,web.structured-clone

（实际测试命令以仓库根目录 package.json 中的 scripts 为准；对应测试文件位于 tests/unit-global 目录。）

进一步阅读建议：

• 未来规划与版本走向见 docs/2023-02-14-so-whats-next.md（另有中文版 docs/zh_CN/2023-02-14-so-whats-next.md），其中讨论了 core-js@4 的相关计划；
• 纯版（无污染）使用说明见 packages/core-js-pure/README.md；
• 目标环境兼容矩阵与按环境裁剪的能力由 packages/core-js-compat/README.md 提供。

七、注意事项

• 引入位置：作为 polyfill，core-js 的 import 应放在应用/库入口的最前面，保证后续代码执行时特性已就绪；
• 打包体积：优先采用 3.2 按需加载或借助 core-js-compat 按目标浏览器裁剪，避免全量引入；
• 版本演进：proposals/index.js 中标注了计划在 core-js@4 移除该入口，提案特性请以官方文档（仓库 docs 目录）的当前推荐路径为准；
• 环境假设：上述示例基于 ES Module 语法；在 CommonJS 环境下将 import 替换为 require 即可，行为一致。

综上，core-js 的核心价值在于"标准化、模块化、可选择"：把 ECMAScript 截至 2026 的定稿特性、提案特性与 WHATWG/W3C Web 标准统一收编，并提供从全量引入、按需引入到零污染引用的完整谱系，是 JavaScript 跨环境能力补齐的重要基础设施。