跳至主内容

@babel/register

非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

使用 Babel 的方式之一是通过 require 钩子。该钩子会绑定到 Node.js 的 require 函数上，在文件加载时自动进行实时编译。这相当于 CoffeeScript 的 coffee-script/register。

安装​

npm install @babel/core @babel/register --save-dev

用法​

JavaScript
require("@babel/register");

所有被 node 加载的后续文件（扩展名为 .es6、.es、.jsx、.mjs 和 .js）都将由 Babel 转换。

未包含 Polyfill

使用需要 polyfill 的功能（如生成器）时，必须单独引入 polyfill。

默认忽略 node_modules​

注意： 默认情况下，所有对 node_modules 的引用都会被忽略。可通过传入忽略正则表达式覆盖此行为：

JavaScript
require("@babel/register")({
  // This will override `node_modules` ignoring - you can alternatively pass
  // an array of strings to be explicitly matched or a regex / glob
  ignore: [],
});

指定选项​

JavaScript
require("@babel/register")({
  // Array of ignore conditions, either a regex or a function. (Optional)
  // File paths that match any condition are not compiled.
  ignore: [
    // When a file path matches this regex then it is **not** compiled
    /regex/,

    // The file's path is also passed to any ignore functions. It will
    // **not** be compiled if `true` is returned.
    function(filepath) {
      return filepath !== "/path/to/es6-file.js";
    },
  ],

  // Array of accept conditions, either a regex or a function. (Optional)
  // File paths that match all conditions are compiled.
  only: [
    // File paths that **don't** match this regex are not compiled
    /my_es6_folder/,

    // File paths that **do not** return true are not compiled
    function(filepath) {
      return filepath === "/path/to/es6-file.js";
    },
  ],

  // Setting this will remove the currently hooked extensions of `.es6`, `.es`, `.jsx`, `.mjs`
  // and .js so you'll have to add them back if you want them to be used again.
  extensions: [".es6", ".es", ".jsx", ".js", ".mjs"],

  // Setting this to false will disable the cache.
  cache: true,
});

可传入所有其他选项，包括 plugins 和 presets。请注意配置文件也会被加载，编程式配置将覆盖文件配置选项。@babel/register 不支持在配置文件中使用 ignore 和 only。

环境变量​

默认情况下，@babel/node CLI 和 @babel/register 会将 JSON 缓存保存到临时目录。

这将显著提升文件启动和编译速度。但在某些场景下，可能需要更改此行为，因此提供了以下环境变量：

BABEL_CACHE_PATH​

指定不同的缓存位置。

Shell
BABEL_CACHE_PATH=/foo/my-cache.json babel-node script.js

BABEL_DISABLE_CACHE​

禁用缓存。

Shell
BABEL_DISABLE_CACHE=1 babel-node script.js

实时编译插件和预设​

@babel/register 使用 Node.js 的 require() 钩子系统在文件加载时实时编译。虽然这非常实用，但也可能导致复杂情况：require() 钩子内的代码可能触发 更多 require 调用，形成依赖循环。例如在 Babel 场景中，编译用户文件时可能意外尝试在 加载过程中 编译自身。

为避免此问题，该模块明确禁止可重入编译，即 Babel 自身的编译逻辑无法触发其他文件的实时编译。代价是：如需定义需实时编译的插件或预设，过程将变得复杂。

关键在于需由你的代码优先加载插件/预设。假设插件/预设会提前加载所有依赖，你需要：

require("@babel/register")({
  // ...
});

require("./my-plugin");

由于加载由你的代码触发（而非 @babel/register 内部逻辑），这将成功编译任何同步加载的插件/预设。

Babel 8 实验性实现​

可通过以下方式测试 Babel 8 将默认启用的实验性实现：

JavaScript
require("@babel/register/experimental-worker");

它在内部异步运行 Babel，因此兼容 .mjs 配置文件。现已可作为 @babel/register 的替代方案，但需注意：

  • 若以编程方式指定 @babel/register 选项（使用 require("@babel/register")({ /* ... options */ })），必须确保选项可序列化。这意味着不能传递内联定义的插件函数，而需将其移至单独的 ./my-plugin.js 文件或 babel.config.js 文件。

  • 新实现仍处于实验阶段：它_应该_具备与现有实现相同的功能，但可能存在新的错误和功能退化问题。

注意：@babel/register _不_支持在运行时编译原生的 Node.js ES 模块，因为目前没有稳定的 API 可用于拦截 ES 模块加载。