`@typescript-eslint/parser`

一个 ESLint 解析器用于将 TypeScript 代码解析为 ESLint 兼容的节点，并提供支持的 TypeScript 程序。✨

这是必要的，因为 TypeScript 生成的 AST 格式与 ESLint 需要的格式不同，不兼容。例如，以下代码不是有效的 JavaScript 代码，因为它包含 : number 类型注解

let x: number = 1;

ESLint 的原生 Espree 解析器在尝试解析它时会报错。

此外，由于 TypeScript 是独立开发的，并且与 ESLint、ESTree 和 Espree 的目标不同，它的 AST 在许多情况下也以不同的方式表示节点。TS 的 AST 针对其解析不完整代码和类型检查的用例进行了优化。ESTree 未经优化，旨在用于遍历 AST 的“通用”用例。

提示

您可以在 typescript-eslint playground 的右侧边栏中选择 ESTree 来选择 @typescript-eslint/parser。

配置

通过在您的 ESLint 配置文件中指定 parserOptions，可以使用以下额外的配置选项。

interface ParserOptions {
  allowAutomaticSingleRunInference?: boolean;
  cacheLifetime?: {
    glob?: number | 'Infinity';
  };
  ecmaFeatures?: {
    jsx?: boolean;
    globalReturn?: boolean;
  };
  ecmaVersion?: number | 'latest';
  emitDecoratorMetadata?: boolean;
  experimentalDecorators?: boolean;
  extraFileExtensions?: string[];
  jsDocParsingMode?: 'all' | 'none' | 'type-info';
  jsxFragmentName?: string | null;
  jsxPragma?: string | null;
  lib?: string[];
  programs?: import('typescript').Program[];
  project?: string | string[] | boolean | null;
  projectFolderIgnoreList?: string[];
  tsconfigRootDir?: string;
  warnOnUnsupportedTypeScriptVersion?: boolean;
  EXPERIMENTAL_useProjectService?: boolean;
}

`allowAutomaticSingleRunInference`

默认值为 process.env.TSESTREE_SINGLE_RUN 或 false。

是否使用常见的启发式方法来推断 ESLint 是否作为单次运行的一部分使用（与 `--fix` 模式或持久会话（如编辑器扩展）相反）。

当 typescript-eslint 在幕后处理 TypeScript 程序管理以进行带有类型信息的代码检查时，这种区别对于性能至关重要。管理用于长时间运行用例的 TypeScript “Watch” 程序会带来很大的开销。能够假设单次运行情况允许 typescript-eslint 使用更快的不可变程序。

此设置的默认值可以通过将 `TSESTREE_SINGLE_RUN` 环境变量设置为 `“false”` 或 `“true”` 来指定。例如，`TSESTREE_SINGLE_RUN=true npx eslint .` 将启用它。

提示

我们已经看到 `allowAutomaticSingleRunInference` 在 CI 中将代码检查速度提高了 10-20%。我们的计划是在即将发布的主要版本中默认启用 `allowAutomaticSingleRunInference`。

`cacheLifetime`

此选项允许您细粒度地控制我们内部缓存的过期时间长度。

您可以将秒数指定为整数，或者如果永远不想让缓存过期，则指定字符串 'Infinity'。

默认情况下，缓存条目将在 30 秒后被清除，或者如果解析器推断出它是单次运行（请参阅 allowAutomaticSingleRunInference），则会无限期地保留。

`ecmaFeatures`

描述如何解析原始语法的可选附加选项。

`jsx`

默认值为 `false`。

当 `true` 时，启用解析 JSX。有关更多详细信息，请参阅 TypeScript 手册的 JSX 文档。

注意：此设置不影响已知文件类型（`.js`、`.mjs`、`.cjs`、`.jsx`、`.ts`、`.mts`、`.cts`、`.tsx`、`.json`），因为 TypeScript 编译器有自己的内部处理机制来处理已知文件扩展名。

确切的行为如下

`.js`、`.mjs`、`.cjs`、`.jsx`、`.tsx` 文件始终被解析为如果此值为 `true`。
`.ts`、`.mts`、`.cts` 文件始终被解析为如果此值为 `false`。
对于“未知”扩展名（`.md`、`.vue`）
- 如果未提供 `parserOptions.project`
  - 将尊重此设置。
- 如果提供了 `parserOptions.project`（即您正在使用带有类型信息的规则）
  - 始终解析为false

`globalReturn`

默认值为 `false`。

此选项允许您告诉解析器是否要在代码库中允许全局return语句。

`ecmaVersion`

默认值为2018。

接受任何有效的 ECMAScript 版本号或'latest'

版本：es3、es5、es6、es7、es8、es9、es10、es11、es12、es13，...，或
年份：es2015、es2016、es2017、es2018、es2019、es2020、es2021、es2022，...，或
'latest'

当它是一个版本或年份时，该值**必须**是一个数字 - 所以不要包含es前缀。

指定要使用的 ECMAScript 语法版本。解析器使用它来确定如何执行作用域分析，并且它会影响默认的

`emitDecoratorMetadata`

默认值为undefined。

此选项允许您告诉解析器像在tsconfig.json中设置了emitDecoratorMetadata: true一样工作，但没有类型感知的代码风格检查。换句话说，在这种情况下，您不必指定parserOptions.project，从而使代码风格检查过程更快。

`experimentalDecorators`

默认值为undefined。

此选项允许您告诉解析器像在tsconfig.json中设置了experimentalDecorators: true一样工作，但没有类型感知的代码风格检查。换句话说，在这种情况下，您不必指定parserOptions.project，从而使代码风格检查过程更快。

`extraFileExtensions`

默认值为undefined。

此选项允许您提供一个或多个额外的文件扩展名，这些扩展名应在 TypeScript Program 编译中考虑。默认扩展名是['.js', '.mjs', '.cjs', '.jsx', '.ts', '.mts', '.cts', '.tsx']。添加以.开头的扩展名，后跟文件扩展名。例如，对于.vue文件，使用"extraFileExtensions": [".vue"]。

`jsDocParsingMode`

如果设置了 parserOptions.project，则默认为 'all'，否则为 'none'

当 TS 解析文件时，它也会将 JSDoc 注释解析到 AST 中，然后 lint 规则可以利用这些注释。如果您使用的是 TypeScript 版本 >= 5.3，则可以使用此选项作为性能优化。

此规则的有效值为

'all' - 始终解析所有 JSDoc 注释。
'none' - 从不解析任何 JSDoc 注释。
'type-info' - 只解析提供正确类型信息的 JSDoc 注释。TS 始终会在非 TS 文件中解析 JSDoc，但在 TS 文件中则不会。

如果您不使用依赖于 TS 的 JSDoc 标签表示的 lint 规则（例如 eslint-plugin-deprecation），则可以将其设置为 'none' 以提高解析器性能。

`jsxFragmentName`

默认值 null

用于 JSX 片段元素的标识符（在转译后）。如果为 null，则假设转译将始终使用配置的 jsxPragma 的成员。这不能是成员表达式 - 只能是根标识符（例如，使用 "h" 而不是 "h.Fragment"）。

如果您提供了 parserOptions.project，则无需设置此选项，因为它将从编译器中自动检测。

`jsxPragma`

默认值 'React'

用于 JSX 元素创建的标识符（在转译后）。如果您使用的是除 React 之外的库（例如 preact），则应更改此值。如果您使用的是新的 JSX 转译，则可以将其设置为 null。

这不能是成员表达式 - 只能是根标识符（例如，使用 "React" 而不是 "React.createElement"）。

如果您提供了 parserOptions.project，则无需设置此选项，因为它将从编译器中自动检测。

`lib`

默认值 ['es2018']

有关有效选项，请参阅 TypeScript 编译器选项。

指定可用的 TypeScript lib。作用域分析器使用它来确保为 TypeScript 公开的类型声明了全局变量。

如果您提供了 parserOptions.project，则无需设置此选项，因为它将从编译器中自动检测。

`programs`

默认值为undefined。

此选项允许您以编程方式提供 TypeScript Program 对象的实例，该实例将为规则提供类型信息。这将覆盖从 parserOptions.project 计算出的任何程序。所有 lint 的文件都必须是提供的程序的一部分。

有关如何编写 resolveModuleNames 函数的示例，请参阅 TypeScript Wiki。.

`project`

默认值为undefined。

指向您项目 TSConfig 的路径。此设置是使用需要类型信息的规则所必需的。

接受的值类型

// find the tsconfig.json nearest to each source file
project: true,

// path
project: './tsconfig.json';

// glob pattern
project: './packages/**/tsconfig.json';

// array of paths and/or glob patterns
project: ['./packages/**/tsconfig.json', './separate-package/tsconfig.json'];

// ways to disable type-aware linting (useful for overrides configs)
project: false;
project: null;

如果为 true，则每个源文件的解析将找到该源文件最近的 tsconfig.json 文件。
- 这是通过检查源文件的目录树以查找最近的 tsconfig.json 来完成的。
如果您使用项目引用，TypeScript 不会自动使用项目引用来解析文件。这意味着您必须将每个引用的 tsconfig 分别添加到 project 字段中，或者通过通配符添加。
请注意，在您的 parserOptions.project 中使用宽通配符 ** 可能会导致性能问题。与使用 ** 递归检查所有文件夹的通配符相比，最好使用一次使用单个 * 的路径。有关更多信息，请参阅 #2611。
TypeScript 将忽略同一文件夹中具有重复文件名的文件（例如，src/file.ts 和 src/file.js）。TypeScript 故意忽略除一个文件以外的所有文件，只保留具有最高优先级扩展名的文件（扩展名优先级顺序（从最高到最低）为 .ts、.tsx、.d.ts、.js、.jsx）。有关更多信息，请参阅 #955。

注意

如果未设置 tsconfigRootDir，则相对路径将相对于当前工作目录进行解释。

如果指定了此设置，您只能对项目中包含的文件进行 lint，这些文件由提供的 TSConfig 文件定义。如果您的现有配置不包含您想要 lint 的所有文件，您可以创建一个单独的 tsconfig.eslint.json 文件，如下所示

{
  // extend your base config so you don't have to redefine your compilerOptions
  "extends": "./tsconfig.json",
  "include": [
    "src/**/*.ts",
    "test/**/*.ts",
    "typings/**/*.ts",
    // etc

    // if you have a mixed JS/TS codebase, don't forget to include your JS files
    "src/**/*.js",
  ],
}

有关允许对 TSConfig 文件之外的文件进行 lint 的选项，请参阅 EXPERIMENTAL_useProjectService.

`projectFolderIgnoreList`

默认值 ["**/node_modules/**"]。

此选项允许您忽略从提供的 project 列表中包含的文件夹。如果您配置了 glob 模式，但想要确保忽略某些文件夹，这将很有用。

它接受一个 glob 数组，从 project glob 中排除。

例如，默认情况下，它将确保像 ./**/tsconfig.json 这样的 glob 不会匹配 node_modules 文件夹中的任何 tsconfig（某些 npm 包不会从其发布的包中排除其源文件）。

`tsconfigRootDir`

默认值为undefined。

此选项允许您为上面 project 选项中指定的相对 TSConfig 路径提供根目录。这样做可以确保从根目录以外的目录运行 ESLint 仍然能够找到您的 TSConfig。

`warnOnUnsupportedTypeScriptVersion`

默认值 true。

此选项允许您切换解析器在您使用未明确支持的 TypeScript 版本时给您的警告。警告消息将如下所示

=============

WARNING: You are currently running a version of TypeScript which is not officially supported by @typescript-eslint/typescript-estree.

You may find that it works just fine, or you may not.

SUPPORTED TYPESCRIPT VERSIONS: >=3.3.1 <5.1.0

YOUR TYPESCRIPT VERSION: 5.1.3

Please only submit bug reports when using the officially supported version.

=============

`EXPERIMENTAL_useProjectService`

默认值为 `false`。

parserOptions.project 的实验性替代方案。这指示解析器使用更无缝的 TypeScript API 为规则生成类型信息。它将自动检测每个文件的 TSConfig（如 project: true），并且还允许为没有 allowJs 编译器选项的 JavaScript 文件计算类型信息（与 project: true 不同）。

扁平配置
旧版配置

eslint.config.js
export default [
  {
    languageOptions: {
      parserOptions: {
        EXPERIMENTAL_useProjectService: true,
      },
    },
  },
];

.eslintrc.js
module.exports = {
  parser: '@typescript-eslint/parser',
  parserOptions: {
    EXPERIMENTAL_useProjectService: true,
  },
};

此选项应该带来两个主要好处

更简单的配置：大多数项目不需要显式配置project路径或创建tsconfig.eslint.json
性能提升：此 API 在 TypeScript 方面针对速度进行了优化
- 此选项的初始版本在 typescript-eslint 单仓库的子集中展示了性能变化，从慢 11% 到快 70% 不等

我们希望此选项最终将成为启用类型化 lint 的标准方式。它将解析器从手动创建 TypeScript 程序切换为改为调用与 VS Code 等编辑器使用的相同“项目服务” API。但是，由于它非常新且未经测试，因此我们至少在所有 6.X 版本中将其保留在 EXPERIMENTAL_ 前缀下。

实用程序

`createProgram(configFile, projectDirectory)`

这作为 parserOptions.programs 功能用户的实用程序方法，用于从配置文件创建 TypeScript 程序实例。

declare function createProgram(
  configFile: string,
  projectDirectory?: string,
): import('typescript').Program;

示例用法

扁平配置
旧版配置

eslint.config.js
import * as parser from '@typescript-eslint/parser';

export default [
  {
    parserOptions: {
      programs: [parser.createProgram('tsconfig.json')],
    },
  },
];

.eslintrc.js
const parser = require('@typescript-eslint/parser');

module.exports = {
  parserOptions: {
    programs: [parser.createProgram('tsconfig.json')],
  },
};

`withoutProjectParserOptions(parserOptions)`

删除提示解析器使用类型信息解析项目的选项。换句话说，如果您直接调用解析器，可以使用它来确保单个文件将被隔离解析，这要快得多。

这在您直接调用解析器的情况下很有用，例如在 ESLint 插件上下文中。

declare function withoutProjectParserOptions(
  options: TSESTreeOptions,
): TSESTreeOptions;

示例用法

somePlugin.js
const parser = require('@typescript-eslint/parser');

function parse(path, content, context) {
  const contextParserOptions = context.languageOptions?.parserOptions ?? {};
  const parserOptions =
    parser.withoutProjectParserOptions(contextParserOptions);

  // Do something with the cleaned-up options eventually, such as invoking the parser
  parser.parseForESLint(content, parserOptions);
}

@typescript-eslint/parser

配置​

allowAutomaticSingleRunInference​

cacheLifetime​

ecmaFeatures​

jsx​

globalReturn​

ecmaVersion​

emitDecoratorMetadata​

experimentalDecorators​

extraFileExtensions​

jsDocParsingMode​

jsxFragmentName​

jsxPragma​

lib​

programs​

project​

projectFolderIgnoreList​

tsconfigRootDir​

warnOnUnsupportedTypeScriptVersion​

EXPERIMENTAL_useProjectService​

实用程序​

createProgram(configFile, projectDirectory)​

withoutProjectParserOptions(parserOptions)​

`@typescript-eslint/parser`

配置

`allowAutomaticSingleRunInference`

`cacheLifetime`

`ecmaFeatures`

`jsx`

`globalReturn`

`ecmaVersion`

`emitDecoratorMetadata`

`experimentalDecorators`

`extraFileExtensions`

`jsDocParsingMode`

`jsxFragmentName`

`jsxPragma`

`lib`

`programs`

`project`

`projectFolderIgnoreList`

`tsconfigRootDir`

`warnOnUnsupportedTypeScriptVersion`

`EXPERIMENTAL_useProjectService`

实用程序

`createProgram(configFile, projectDirectory)`

`withoutProjectParserOptions(parserOptions)`