`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` 的重新导出
`FlatConfig`	从 `@typescript-eslint/utils` 重新导出类型

安装

¥Installation

npm
Yarn
pnpm

npm i typescript-eslint

yarn add typescript-eslint

pnpm add typescript-eslint

用法

¥Usage

我们建议首先使用默认的 ESLint 设置和我们的共享配置。

¥We recommend getting started by using the default ESLint setup with our shared configs.

eslint.config.mjs
// @ts-check

import eslint from '@eslint/js';
import { defineConfig } from 'eslint/config';
import tseslint from 'typescript-eslint';

export default defineConfig(
  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(...)`（已弃用）

¥config(...) (deprecated)

危险

config(...) 实用程序函数已弃用，取而代之的是 #10935 中的 ESLint 核心的 defineConfig(...)。请参阅稍后会发布 defineConfig 迁移指南以了解更多详细信息。

¥The config(...) utility function was deprecated in favor of ESLint core's defineConfig(...) in #10935. See the defineConfig migration guide later for more details.

此处的文档保留用于历史参考和迁移目的。

¥The documentation here is preserved for historical reference and migration purposes.

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
Without 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,
  {
    /*... */
  },
  // ...
);

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',
  },
});

迁移到 `defineConfig(...)`

¥Migrating to defineConfig(...)

核心 defineConfig(...) 助手几乎与 tseslint.config(...)（即首次发布于 ESLint v9.22.0）完全相同。有关如何在旧版本的 ESLint 中使用 defineConfig(...)，请参阅 ESLint 博客文章。

¥The core defineConfig(...) helper is a nearly exact clone of tseslint.config(...) that was first released in ESLint v9.22.0. See the ESLint blog post for info on how to use defineConfig(...) with older versions of ESLint.

在撰写本文时，已知少数边缘情况，其中两者具有不同的功能。

¥At the time of writing there are a small number of known edge cases in which the two have different functionality.

在 extends 中覆盖 files。当基础对象和扩展中都提供 files 时，tseslint.config(...) 会覆盖扩展中的 files 属性，而 defineConfig(...) 在语义上与提供的两个 files 说明符相交。

¥Overriding files in extends. When files is provided in both a base object and an extension, tseslint.config(...) overrides the files property in the extension, whereas defineConfig(...) semantically intersects the two provided files specifiers.

tseslint.config(...)
defineConfig(...)

eslint.config.mjs
import tseslint from 'typescript-eslint';

export default tseslint.config({
  files: ['a.ts'],
  extends: [
    {
      files: ['b.ts'],
      rules: {
        'some-rule': 'error',
      },
    },
  ],
});

// is equivalent to

export default {
  files: ['a.ts'],
  rules: { 'some-rule': 'error' },
};

eslint.config.mjs
import { defineConfig } from 'eslint/config';

export default defineConfig({
  files: ['a.ts'],
  extends: [
    {
      files: ['b.ts'],
      rules: {
        'some-rule': 'error',
      },
    },
  ],
});

// is equivalent to

// The base config technically ensures that 'a.ts' is still included in
// the lint run, but otherwise the config has no effect, due to the
// intersection of 'a.ts' and 'b.ts' being empty.
export default {
  files: ['a.ts'],
};

类型声明（仅适用于对其 eslint 配置进行类型检查的用户）。这两个函数的类型声明方式略有不同，在某些情况下，当你从 tseslint.config(...) 切换到 defineConfig(...) 时，这可能会导致类型检查错误（请参阅 #10899 中的示例，该示例曾影响 typescript-eslint 自身的配置）。此类类型错误并不表示运行时问题，可以安全地忽略。

¥Type declarations (only applies to users who typecheck their eslint configs). There are slight differences in the way types are declared between the two functions, which may cause typechecking errors when you switch from tseslint.config(...) to defineConfig(...) in some cases (see #10899 for an example that used to impact typescript-eslint's own configs). Type errors such as these do not indicate a runtime problem and can safely be ignored.

手动使用

¥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 { defineConfig } from 'eslint/config';
import jestPlugin from 'eslint-plugin-jest';
import tseslint from 'typescript-eslint';

export default defineConfig({
  plugins: {
    '@typescript-eslint': tseslint.plugin,
  },
  languageOptions: {
    parser: tseslint.parser,
    parserOptions: {
      projectService: true,
    },
  },
  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 { defineConfig } from 'eslint/config';
import jestPlugin from 'eslint-plugin-jest';
import tseslint from 'typescript-eslint';

export default defineConfig(
  {
    // 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
Yarn
pnpm

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

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

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.

安装​

用法​

config(...)（已弃用）​

扁平配置 extends​

迁移到 defineConfig(...)​

手动使用​

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

与其他插件一起使用​

从旧版 .eslintrc 配置迁移​

安装

用法