Skip to main content

@babel/eslint-parser

@babel/eslint-parser allows you to lint all valid Babel code with the fantastic ESLint.

何时应该使用 @babel/eslint-parser？​

¥When should I use @babel/eslint-parser?

ESLint 的默认解析器和核心规则 仅支持最新的最终 ECMAScript 标准 不支持 Babel 提供的实验性语法（例如新功能）和非标准语法（例如 Flow 或 TypeScript 类型）。@babel/eslint-parser is a parser that allows ESLint to run on source code that is transformed by Babel.

¥ESLint's default parser and core rules only support the latest final ECMAScript standard and do not support experimental (such as new features) and non-standard (such as Flow or TypeScript types) syntax provided by Babel. @babel/eslint-parser is a parser that allows ESLint to run on source code that is transformed by Babel.

注意：如果你使用 Babel 转换代码，则只需使用 @babel/eslint-parser。如果不是这种情况，请使用与你选择的 ECMAScript 风格相关的解析器（请注意，默认解析器支持所有非实验性语法以及 JSX）。

¥Note: You only need to use @babel/eslint-parser if you are using Babel to transform your code. If this is not the case, please use the relevant parser for your chosen flavor of ECMAScript (note that the default parser supports all non-experimental syntax as well as JSX).

它是如何工作的？​

¥How does it work?

ESLint 允许使用 自定义解析器。使用此插件时，你的代码将由 Babel 的解析器解析（使用你在 Babel 配置文件 中指定的配置），并将生成的 AST 转换为 ESLint 可以理解的符合 ESTree 的结构。所有位置信息（例如行号、列）也会保留，以便你轻松追踪错误。

¥ESLint allows for the use of custom parsers. When using this plugin, your code is parsed by Babel's parser (using the configuration specified in your Babel configuration file) and the resulting AST is transformed into an ESTree-compliant structure that ESLint can understand. All location info such as line numbers, columns is also retained so you can track down errors with ease.

注意：ESLint 的核心规则不支持实验性语法，因此在使用 @babel/eslint-parser 时可能无法按预期工作。如果你遇到核心规则问题，请使用配套的 @babel/eslint-plugin 插件。

¥Note: ESLint's core rules do not support experimental syntax and may therefore not work as expected when using @babel/eslint-parser. Please use the companion @babel/eslint-plugin plugin for core rules that you have issues with.

用法​

¥Usage

安装​

¥Installation

npm install eslint @babel/core @babel/eslint-parser --save-dev

注意：@babel/eslint-parser requires @babel/core@>=7.2.0 and a valid Babel configuration file to run.如果你尚未设置，请参阅 Babel 使用指南。

¥Note: @babel/eslint-parser requires @babel/core@>=7.2.0 and a valid Babel configuration file to run. If you do not have this already set up, please see the Babel Usage Guide.

设置​

¥Setup

要使用 @babel/eslint-parser，必须在 ESLint 配置文件中将 "@babel/eslint-parser" 指定为 parser（有关更多详细信息，请参阅 此处）。

¥To use @babel/eslint-parser, "@babel/eslint-parser" must be specified as the parser in your ESLint configuration file (see here for more detailed information).

import babelParser from "@babel/eslint-parser";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.js", "**/*.cjs", "**/*.mjs"],
    languageOptions: {
      parser: babelParser,
    },
  },
]);

设置解析器后，你可以按照 配置 ESLint 文档中的说明进行配置。

¥With the parser set, your configuration can be configured as described in the Configuring ESLint documentation.

注意：官方文档 中描述的 parserOptions 适用于默认解析器，@babel/eslint-parser 不一定支持。请参阅下面的部分，了解支持的 parserOptions。

¥Note: The parserOptions described in the official documentation are for the default parser and are not necessarily supported by @babel/eslint-parser. Please see the section directly below for supported parserOptions.

额外的解析器配置​

¥Additional parser configuration

你可以在 ESLint 配置中的 parserOptions 键下设置其他配置选项。请注意，默认情况下，ESLint 可能仍然需要 ecmaFeatures 配置属性才能正确使用 ECMAScript 5 中没有的功能。

¥Additional configuration options can be set in your ESLint configuration under the parserOptions key. Please note that the ecmaFeatures config property may still be required for ESLint to work properly with features not in ECMAScript 5 by default.

  • 可以将 requireConfigFile（默认 true）设置为 false，以允许 @babel/eslint-parser 在没有关联 Babel 配置的文件上运行。这对于检查未经 Babel 转换的文件（例如工具配置文件）非常有用，但我们建议通过 基于 glob 的配置 使用默认解析器。注意：当 requireConfigFile 为 false 时，@babel/eslint-parser 仍将尝试加载根 babel 配置。如果未找到配置文件，@babel/eslint-parser 将不会解析任何实验性语法。虽然不推荐，但如果你有 babel 配置，但希望阻止 @babel/eslint-parser 加载 Babel 配置，请指定

    ¥requireConfigFile (default true) can be set to false to allow @babel/eslint-parser to run on files that do not have a Babel configuration associated with them. This can be useful for linting files that are not transformed by Babel (such as tooling configuration files), though we recommend using the default parser via glob-based configuration. Note: When requireConfigFile is false, @babel/eslint-parser will still try to load the root babel config. If no configuration file is found, @babel/eslint-parser will not parse any experimental syntax. Though not recommended, if you have a babel config, but would like to prevent @babel/eslint-parser from loading Babel config, please specify

import babelParser from "@babel/eslint-parser";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.js", "**/*.cjs", "**/*.mjs"],
    languageOptions: {
      parser: babelParser,
      parserOptions: {
        requireConfigFile: false,
        babelOptions: {
          babelrc: false,
          configFile: false,
          // your babel options
          presets: ["@babel/preset-env"],
        },
      },
    },
  },
]);

eslint.config.js

  • sourceType 可以设置为 "module"（默认）、"script" 或 "commonjs"。

    ¥sourceType can be set to "module"(default), "script" or "commonjs".

  • ecmaFeatures.globalReturn（默认 false）与 sourceType: "script" 一起使用时，允许在全局范围内返回语句。此选项将被弃用，请使用 sourceType: "commonjs" 代替。

    ¥ecmaFeatures.globalReturn (default false) allow return statements in the global scope when used with sourceType: "script". This option will be deprecated, please use sourceType: "commonjs" instead.

  • babelOptions 是一个包含 Babel 配置 选项 的对象，这些配置在运行时传递给 Babel 的解析器。适用于用户可能不想使用 Babel 配置文件或通过其他工具（例如带有 babel-loader 的 Webpack）运行 Babel 的情况。

    ¥babelOptions is an object containing Babel configuration options that are passed to Babel's parser at runtime. For cases where users might not want to use a Babel configuration file or are running Babel through another tool (such as Webpack with babel-loader).

  • 如果你的构建环境支持，可以将 allowImportExportEverywhere（默认 false）设置为 true，以允许 import 和 export 声明出现在允许语句的任何位置。否则，导入和导出声明只能出现在程序的顶层。

    ¥allowImportExportEverywhere (default false) can be set to true to allow import and export declarations to appear anywhere a statement is allowed if your build environment supports that. Otherwise import and export declarations can only appear at a program's top level.

自定义 Babel 配置路径​

¥customize Babel config path

import babelParser from "@babel/eslint-parser";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.js", "**/*.cjs", "**/*.mjs"],
    languageOptions: {
      parser: babelParser,
      parserOptions: {
        requireConfigFile: false,
        babelOptions: {
          babelrc: false,
          configFile: "path/to/babel.config.js",
        },
      },
    },
  },
]);

使用 babel.config.mjs 配置​

¥use babel.config.mjs configuration

如果你的 Babel 配置不包含顶层 await，你应该能够在 Node.js 22.12 或更高版本上直接使用 .mjs 配置。否则，你可以使用实验性的 Worker 实现。请注意，该实现仍处于实验阶段，如果你发现任何问题，请报告。

¥If your Babel config does not contain top-level await, you should be able to use the .mjs config directly on Node.js 22.12 or above. Otherwise, you can use the experimental worker implementation. Note that the implementation is still experimental, please report if you find any issue.

import babelParserExperimentalWorker from "@babel/eslint-parser/experimental-worker";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.js", "**/*.cjs", "**/*.mjs"],
    languageOptions: {
      parser: babelParserExperimentalWorker,
      parserOptions: {
        requireConfigFile: false,
        babelOptions: {
          babelrc: false,
          configFile: "path/to/babel.config.mjs",
        },
      },
    },
  },
]);

使用基于 glob 的配置​

¥use glob-based configuration

此配置将对除 "files/transformed/by/babel/*.js" glob 找到的文件之外的所有文件使用默认解析器。

¥This configuration would use the default parser for all files except for those found by the "files/transformed/by/babel/*.js" glob.

import babelParser from "@babel/eslint-parser";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["files/transformed/by/babel/*.js"],
    languageOptions: {
      parser: babelParser,
    },
  },
]);

Monorepo 配置​

¥Monorepo configuration

此配置对于 monorepo 很有用，当你在每个包上运行 ESLint 而不是从 monorepo 根文件夹运行时，因为它避免了在每个包上重复 Babel 和 ESLint 配置。

¥This configuration is useful for monorepo, when you are running ESLint on every package and not from the monorepo root folder, as it avoids to repeat the Babel and ESLint configuration on every package.

import babelParser from "@babel/eslint-parser";
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.js", "**/*.cjs", "**/*.mjs"],
    languageOptions: {
      parser: babelParser,
      parserOptions: {
        babelOptions: {
          rootMode: "upward",
        },
      },
    },
  },
]);

运行​

¥Run

./node_modules/.bin/eslint yourfile.js

TypeScript​

虽然 @babel/eslint-parser 可以解析 TypeScript，但我们目前不支持使用 @babel/eslint-plugin 中的规则对 TypeScript 进行 linting。这是因为 TypeScript 社区已经以 @typescript-eslint 为中心，我们希望避免重复工作。此外，由于 @typescript-eslint 底层使用 TypeScript，因此其规则可以实现类型感知，这是 Babel 无法做到的。

¥While @babel/eslint-parser can parse TypeScript, we don't currently support linting TypeScript using the rules in @babel/eslint-plugin. This is because the TypeScript community has centered around @typescript-eslint and we want to avoid duplicate work. Additionally, since @typescript-eslint uses TypeScript under the hood, its rules can be made type-aware, which is something Babel doesn't have the ability to do.