typescript-eslint

使你能够将 TypeScript 与 ESLint 一起使用的工具

¥Tooling which enables you to use TypeScript with ESLint

此包是你可以用来使用我们的 ESLint 工具的主要入口点。

¥This package is the main entrypoint that you can use to consume our tooling with ESLint.

此包导出以下内容：

¥This package exports the following:

名称	描述
config	用于创建类型安全的扁平配置的实用函数 - 请参阅 config(...)
configs	共享 ESLint（扁平）配置
parser	@typescript-eslint/parser 的重新导出
plugin	@typescript-eslint/eslint-plugin 的重新导出

安装

¥Installation

npm

npm i typescript-eslint

Yarn

yarn add typescript-eslint

pnpm

pnpm add typescript-eslint

用法

¥Usage

我们建议首先在 ESLint 配置中使用 tseslint.config 辅助函数：

¥We recommend getting started by using tseslint.config helper function in your ESLint config:

eslint.config.mjs

// @ts-check

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  tseslint.configs.recommended,
);

此配置文件导出一个扁平配置，可同时启用 核心 ESLint 推荐配置 和 我们的推荐配置。

¥This config file exports a flat config that enables both the core ESLint recommended config and our recommended config.

config(...)

tseslint.config(...) 接受任意数量的 ESLint 配置对象，每个对象可能还包含一个要扩展的 extends 配置数组。tseslint.config(...) 返回应用每个扩展的其余设置的等效 ESLint 配置。

¥tseslint.config(...) takes in any number of ESLint config objects, each of which may additionally include an extends array of configs to extend. tseslint.config(...) returns the equivalent ESLint config of applying the rest of the settings for each extension.

通过使用此功能，你将获得所有配置属性的自动补齐和文档。此外，如果你提供无效值，它可能会触发信息性 TypeScript 类型错误。

¥By using this function you will get autocomplete and documentation for all config properties. Additionally, if you provide invalid values, it can trigger informative TypeScript type errors.

With helper

eslint.config.mjs

// @ts-check

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  eslint.configs.recommended,
  tseslint.configs.recommended,
  {
    /*... */
  },
  // ...
);

Without helper

eslint.config.mjs

// @ts-check

import eslint from '@eslint/js';
import tseslint from 'typescript-eslint';

/** @type {import('@typescript-eslint/utils').TSESLint.FlatConfig.ConfigFile} */
export default [
  eslint.configs.recommended,
  ...tseslint.configs.recommended,
  {
    /*... */
  },
  // ...
];

注意

我们强烈建议使用此实用程序来改善配置创作体验 - 但它完全是可选的。如果选择不使用它，你将失去编辑器自动补齐和配置文件的类型检查。否则它不会影响你使用我们工具的能力。

¥We strongly recommend using this utility to improve the config authoring experience — however it is entirely optional. By choosing not to use it you lose editor autocomplete and type checking for config files. Otherwise it will not impact your ability to use our tooling.

扁平配置 extends

¥Flat config extends

tseslint.config 实用程序函数还添加了对扁平配置对象上 extends 属性的处理。这允许你更轻松地扩展特定文件模式的共享配置，同时还可以覆盖这些配置提供的规则/选项：

¥The tseslint.config utility function also adds handling for the extends property on flat config objects. This allows you to more easily extend shared configs for specific file patterns whilst also overriding rules/options provided by those configs:

export default tseslint.config({
  files: ['**/*.ts'],
  extends: [
    eslint.configs.recommended,
    tseslint.configs.recommended,
  ],
  rules: {
    '@typescript-eslint/array-type': 'error',
    // ...
  },
});

// is the same as writing

export default [
  ...[
    eslint.configs.recommended,
    ...tseslint.configs.recommended,
  ].map(conf => ({
    ...conf,
    files: ['**/*.ts'],
  })),
  {
    files: ['**/*.ts'],
    rules: {
      '@typescript-eslint/array-type': 'error',
      // ...
    },
  },
];

我们发现这是编写 ESLint 配置时的常见操作，这就是我们提供此便利属性的原因。

¥We found that this is a common operation when writing ESLint configs which is why we provided this convenience property.

例如，在具有类型感知 linting 的代码库中，类似以下的配置对象是禁用 JavaScript 文件上特定于 TypeScript 的 linting 设置的常用方法：

¥For example, in codebases with type-aware linting, a config object like the following is a common way to disable TypeScript-specific linting setups on JavaScript files:

export default tseslint.config({
  files: ['**/*.js'],
  extends: [tseslint.configs.disableTypeChecked],
  rules: {
    // turn off other type-aware rules
    'other-plugin/typed-rule': 'off',

    // turn off rules that don't apply to JS code
    '@typescript-eslint/explicit-function-return-type': 'off',
  },
});

手动使用

¥Manual usage

typescript-eslint 的推荐和风格配置 为你指定 typescript-eslint parser 和 plugin 选项，因此无需手动提供这些选项。但是，在复杂的 ESLint 配置中，你可能会发现自己需要手动指定这些选项。

¥typescript-eslint's recommended and stylistic configurations specify typescript-eslint parser and plugin options for you, so there is no need to manually provide those. However, in complex ESLint configurations, you may find yourself manually specifying those options yourself.

手动配置我们的插件和解析器

¥Manually configuring our plugin and parser

你可以通过此包在你的配置中声明我们的插件和解析器，例如：

¥You can declare our plugin and parser in your config via this package, for example:

eslint.config.mjs

// @ts-check

import eslint from '@eslint/js';
import jestPlugin from 'eslint-plugin-jest';
import tseslint from 'typescript-eslint';

export default tseslint.config({
  plugins: {
    '@typescript-eslint': tseslint.plugin,
  },
  languageOptions: {
    parser: tseslint.parser,
    parserOptions: {
      projectService: true,
      tsconfigRootDir: import.meta.dirname,
    },
  },
  rules: {
    '@typescript-eslint/no-floating-promises': 'error',
    // ...
  },
});

警告

我们强烈建议使用命名空间 @typescript-eslint 声明我们的插件，如上所示。如果你使用我们的共享配置，这是他们使用的命名空间。多年来，这一直是我们插件的标准命名空间，也是用户最熟悉的。

¥We strongly recommend declaring our plugin with the namespace @typescript-eslint as shown above. If you use our shared configs this is the namespace that they use. This has been the standard namespace for our plugin for many years and is what users are most familiar with.

你可以选择不同的命名空间 - 但请注意，目前是 扁平配置允许在多个命名空间下注册、配置和具有重复报告的相同插件。

¥You may choose a different namespace - but note that currently flat configs allow the same plugin to be registered, configured, and have duplicate reports under multiple namespaces.

与其他插件一起使用

¥Usage with other plugins

下面是一个更复杂的例子，说明如何使用我们的工具进行扁平配置。此配置：

¥Below is a more complex example of how you might use our tooling with flat configs. This config:

• 忽略 build/dist 文件夹被 linted

  ¥Ignores build/dist folders from being linted

• 使用我们的一些流行的类型感知规则启用我们的插件、解析器和类型感知 linting

  ¥Enables our plugin, our parser, and type-aware linting with a few of our popular type-aware rules

• 禁用 JS 文件上的类型感知 linting

  ¥Disables type-aware linting on JS files

• 仅在测试文件上启用推荐的 eslint-plugin-jest 规则

  ¥Enables the recommended eslint-plugin-jest rules on test files only

eslint.config.mjs

// @ts-check

import eslint from '@eslint/js';
import jestPlugin from 'eslint-plugin-jest';
import tseslint from 'typescript-eslint';

export default tseslint.config(
  {
    // config with just ignores is the replacement for `.eslintignore`
    ignores: ['**/build/**', '**/dist/**', 'src/some/file/to/ignore.ts'],
  },
  eslint.configs.recommended,
  {
    plugins: {
      '@typescript-eslint': tseslint.plugin,
      jest: jestPlugin,
    },
    languageOptions: {
      parser: tseslint.parser,
      parserOptions: {
        projectService: true,
      },
    },
    rules: {
      '@typescript-eslint/no-floating-promises': 'error',
      // ...
    },
  },
  {
    // disable type-aware linting on JS files
    files: ['**/*.js'],
    extends: [tseslint.configs.disableTypeChecked],
  },
  {
    // enable jest rules on test files
    files: ['test/**'],
    extends: [jestPlugin.configs['flat/recommended']],
  },
);

从旧版 .eslintrc 配置迁移

¥Migrating from legacy .eslintrc configs

如果你要从旧版 .eslintrc 配置设置迁移，则可能需要单独安装我们的插件和解析器。此包将这些作为依赖包含在内，因此你可以自由卸载本地引用：

¥If you're migrating from a legacy .eslintrc configuration setup you likely have our plugin and parser installed separately. This package includes these as dependencies so you can freely uninstall your local references:

npm

npm un @typescript-eslint/parser @typescript-eslint/eslint-plugin

Yarn

yarn remove @typescript-eslint/parser @typescript-eslint/eslint-plugin

pnpm

pnpm remove @typescript-eslint/parser @typescript-eslint/eslint-plugin

有关从 "legacy" 配置设置迁移的更多信息，请参阅 ESLint 的配置迁移指南。

¥For more information on migrating from a "legacy" config setup, see ESLint's Configuration Migration Guide.