@babel/core

非官方测试版翻译

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

JavaScript

var babel = require("@babel/core");
import { transform } from "@babel/core";
import * as babel from "@babel/core";

所有转换操作都将使用本地的配置文件。

transform

babel.transform(code: string, options?: Object, callback: Function)

转换传入的 code 代码。调用回调函数时，会传入包含生成代码、源码映射(source map)和AST的对象。

JavaScript

babel.transform(code, options, function(err, result) {
  result; // => { code, map, ast }
});

示例

JavaScript

babel.transform("code();", options, function(err, result) {
  result.code;
  result.map;
  result.ast;
});

信息

在 Babel 6 中，此方法是同步的且当时不存在 transformSync。为向后兼容，若未提供回调函数，此函数将表现为同步行为。若您从 Babel 7 开始使用且需要同步操作，请使用 transformSync，此兼容特性将在 Babel 8 中移除。

transformSync

babel.transformSync(code: string, options?: Object)

转换传入的 code 代码。返回包含生成代码、源码映射和AST的对象。

JavaScript

babel.transformSync(code, options); // => { code, map, ast }

示例

JavaScript

var result = babel.transformSync("code();", options);
result.code;
result.map;
result.ast;

transformAsync

babel.transformAsync(code: string, options?: Object)

转换传入的 code 代码。返回解析后包含生成代码、源码映射和AST的Promise对象。

JavaScript

babel.transformAsync(code, options); // => Promise<{ code, map, ast }>

示例

JavaScript

babel.transformAsync("code();", options).then(result => {
  result.code;
  result.map;
  result.ast;
});

transformFile

babel.transformFile(filename: string, options?: Object, callback: Function)

异步转换整个文件内容。

JavaScript

babel.transformFile(filename, options, callback);

示例

JavaScript

babel.transformFile("filename.js", options, function(err, result) {
  result; // => { code, map, ast }
});

transformFileSync

babel.transformFileSync(filename: string, options?: Object)

babel.transformFile 的同步版本。返回 filename 文件的转换后内容。

JavaScript

babel.transformFileSync(filename, options); // => { code, map, ast }

示例

JavaScript

babel.transformFileSync("filename.js", options).code;

transformFileAsync

babel.transformFileAsync(filename: string, options?: Object)

babel.transformFile 的Promise版本。返回解析后包含 filename 文件转换内容的Promise对象。

JavaScript

babel.transformFileAsync(filename, options); // => Promise<{ code, map, ast }>

示例

JavaScript

babel.transformFileAsync("filename.js", options).then(result => {
  result.code;
});

transformFromAst

babel.transformFromAst(ast: Object, code?: string, options?: Object, callback: Function): FileNode | null

基于给定的AST进行转换。

JavaScript

const sourceCode = "if (true) return;";
const parsedAst = babel.parseSync(sourceCode, {
  parserOpts: { allowReturnOutsideFunction: true },
});
babel.transformFromAst(parsedAst, sourceCode, options, function(err, result) {
  const { code, map, ast } = result;
});

信息

在 Babel 6 中，此方法是同步的且当时不存在 transformFromAstSync。为向后兼容，若未提供回调函数，此函数将表现为同步行为。若您从 Babel 7 开始使用且需要同步操作，请使用 transformFromAstSync，此兼容特性将在 Babel 8 中移除。

transformFromAstSync

babel.transformFromAstSync(ast: Object, code?: string, options?: Object)

基于给定的AST进行转换。

JavaScript

const sourceCode = "if (true) return;";
const parsedAst = babel.parseSync(sourceCode, {
  parserOpts: { allowReturnOutsideFunction: true },
});
const { code, map, ast } = babel.transformFromAstSync(
  parsedAst,
  sourceCode,
  options
);

transformFromAstAsync

babel.transformFromAstAsync(ast: Object, code?: string, options?: Object)

基于给定的AST进行转换。

JavaScript

const sourceCode = "if (true) return;";
babel
  .parseAsync(sourceCode, { parserOpts: { allowReturnOutsideFunction: true } })
  .then(parsedAst => {
    return babel.transformFromAstAsync(parsedAst, sourceCode, options);
  })
  .then(({ code, map, ast }) => {
    // ...
  });

parse

babel.parse(code: string, options?: Object, callback: Function)

使用 Babel 的标准行为解析代码。引用的预设（presets）和插件（plugins）将被加载， 相关语法插件会自动启用。

信息

在 Babel 7 的早期测试版中，此方法为同步操作且当时不存在 parseSync。 为保持向后兼容性，若未提供回调函数，此方法将保持同步行为。 如果您使用的是 Babel 7 正式版且需要同步操作，请改用 parseSync， 因为 Babel 8 将不再支持此兼容行为。

parseSync

babel.parseSync(code: string, options?: Object)

返回抽象语法树（AST）。

使用 Babel 的标准行为解析代码。引用的预设（presets）和插件（plugins）将被加载， 相关语法插件会自动启用。

parseAsync

babel.parseAsync(code: string, options?: Object)

返回解析后的 AST 的 Promise 对象。

使用 Babel 的标准行为解析代码。引用的预设（presets）和插件（plugins）将被加载， 相关语法插件会自动启用。

高级 API

许多封装 Babel 的系统需要自动注入插件或预设，或覆盖配置选项。为实现此目标， Babel 提供了若干辅助函数，可在不执行转换的情况下加载部分配置。

loadOptions

babel.loadOptions(options?: Object)

完整解析 Babel 的配置选项，返回的对象包含：

• opts.plugins：完整的 Plugin 实例列表

• opts.presets 为空，所有预设已扁平化并入 opts

• 可安全传回 Babel 使用。类似 "babelrc" 的字段已设为 false， 确保后续调用不会重复加载配置文件

虽然 Plugin 实例不应直接操作，但调用方常将此 opts 序列化为 JSON 作为缓存键值， 表示 Babel 接收的配置选项。此方式不能完全保证缓存失效机制有效， 但目前是最佳实践方案。

loadPartialConfig

babel.loadPartialConfig(options?: Object): PartialConfig

此函数用于支持系统轻松操作和验证用户配置，它会解析插件和预设后立即停止。 预期调用方将操作此配置的 .options 对象， 按需修改后重新传回 Babel。

除标准选项外，此函数额外支持 showIgnoredFiles 选项。 设为 true 时，即使文件被忽略，loadPartialConfig 仍会返回结果（而非 null）。 此功能便于调用方获取影响此结果的文件列表（例如用于监视模式）。 调用方可通过返回的 fileHandling 属性判断文件是否被忽略。

• babelrc: string | void - 文件级配置文件的路径（如果存在）

• babelignore: string | void - .babelignore 文件的路径（如果存在）

• config: string | void - 项目级配置文件的路径（如果存在）

• options: ValidatedOptions - 部分解析后的配置选项，可被修改并再次传递给 Babel

  • plugins: Array<ConfigItem> - 详见下文
  • presets: Array<ConfigItem> - 详见下文
  • 可安全传回给 Babel。类似 "babelrc" 的选项已设为 false，确保后续 Babel 调用不会二次加载配置文件

• hasFilesystemConfig(): boolean - 检查解析后的配置是否从文件系统加载了设置

• fileHandling - 返回值为 "transpile"（转译）、"ignored"（忽略）或 "unsupported"（不支持），告知调用方如何处理该文件

• files - Set 集合，包含构建最终配置时读取的所有文件路径，含项目全局配置、本地配置、扩展配置、忽略文件等。适用于实现监听模式或缓存失效机制

ConfigItem 实例暴露的属性可用于检查值，但每个配置项应视为不可变对象。如需修改，应从列表中移除该配置项，替换为常规 Babel 配置值或通过 babel.createConfigItem 创建的新配置项。有关 ConfigItem 字段详情，请参见该函数说明

createConfigItem

babel.createConfigItem(value: string | {} | Function | [string | {} | Function, {} | void], { dirname?: string, type?: "preset" | "plugin" }): ConfigItem

允许构建工具预先创建并缓存配置项。若对同一插件多次调用此函数，Babel 将多次执行插件函数本身。如需注入确定的插件/预设集合，建议预先构建配置项

ConfigItem 类型

每个 ConfigItem 包含 Babel 已知的全部信息，字段如下：

• value: {} | Function - 插件解析后的值

• options: {} | void - 传递给插件的选项对象

• dirname: string - 选项的相对路径基准目录

• name: string | void - 用户为插件实例指定的名称，如 plugins: [ ['env', {}, 'my-env'] ]

• file: Object | void - 插件文件信息（当 Babel 已知时）

  • request: string - 用户请求的文件路径，如 "@babel/env"
  • resolved: string - 解析后的完整文件路径，如 "/tmp/node_modules/@babel/preset-env/lib/index.js"

DEFAULT_EXTENSIONS

babel.DEFAULT_EXTENSIONS: readonly string[];

Babel 默认支持的文件扩展名列表（".js", ".jsx", ".es6", ".es", ".mjs", "cjs"）。@babel/register 和 @babel/cli 使用此列表确定需转译的文件。该列表不可扩展，但 @babel/cli 提供 --extensions 参数支持其他扩展名

配置选项

完整选项列表详见此处