ESLint 常见问题解答

为什么来自 ESLint 核心的规则无法与 TypeScript 代码正确配合使用？

¥Why is a rule from ESLint core not working correctly with TypeScript code?

发生这种情况是因为 TypeScript 添加了 ESLint 不知道的新功能。

¥This happens because TypeScript adds new features that ESLint doesn't know about.

第一步是 请在此处查看我们的 "extension" 规则列表。扩展规则是扩展基本 ESLint 规则以支持 TypeScript 语法的规则。如果你在那里找到它，请尝试一下，看看它是否适合你。你可以通过禁用基本规则并打开扩展规则来配置它。以下是 semi 规则的示例：

¥The first step is to check our list of "extension" rules here. An extension rule is a rule which extends the base ESLint rules to support TypeScript syntax. If you find it in there, give it a go to see if it works for you. You can configure it by disabling the base rule, and turning on the extension rule. Here's an example with the semi rule:

{
  "rules": {
    "semi": "off",
    "@typescript-eslint/semi": "error"
  }
}

如果你找不到现有的扩展规则，或者扩展规则不适用于你的案例，那么你可以继续检查我们的问题。贡献指南概述了提出问题的最佳方式。

¥If you don't find an existing extension rule, or the extension rule doesn't work for your case, then you can go ahead and check our issues. The contributing guide outlines the best way to raise an issue.

我们每周都会发布新版本的工具。请确保在提交问题之前使用 查看我们最新的 "extension" 规则列表。

¥We release a new version our tooling every week. Please ensure that you check our the latest list of "extension" rules before filing an issue.

即使没有 TypeScript 错误，我也从 no-undef 规则中收到有关未定义全局变量的错误

¥I get errors from the no-undef rule about global variables not being defined, even though there are no TypeScript errors

no-undef lint 规则不使用 TypeScript 来确定存在的全局变量 - 相反，它依赖于 ESLint 的配置。

¥The no-undef lint rule does not use TypeScript to determine the global variables that exist - instead, it relies upon ESLint's configuration.

我们强烈建议你不要在 TypeScript 项目上使用 no-undef lint 规则。它提供的检查已由 TypeScript 提供，无需配置 - TypeScript 在这方面做得更好。

¥We strongly recommend that you do not use the no-undef lint rule on TypeScript projects. The checks it provides are already provided by TypeScript without the need for configuration - TypeScript just does this significantly better.

从我们的 v4.0.0 版本开始，这也适用于类型。如果你使用来自第三方包的全局类型（即来自 @types 包的任何内容），那么你将必须适当地配置 ESLint 以定义这些全局类型。例如;@types/react 中的 JSX 命名空间是你必须在 ESLint 配置中定义的全局第三方类型。

¥As of our v4.0.0 release, this also applies to types. If you use global types from a 3rd party package (i.e. anything from an @types package), then you will have to configure ESLint appropriately to define these global types. For example; the JSX namespace from @types/react is a global 3rd party type that you must define in your ESLint config.

请注意，对于包含 JavaScript 和 TypeScript 的混合项目，可以单独为 TypeScript 文件关闭 no-undef 规则（与任何规则一样），如下所示：

¥Note, that for a mixed project including JavaScript and TypeScript, the no-undef rule (like any rule) can be turned off for TypeScript files alone as follows:

Flat Config

eslint.config.mjs

import tseslint from 'typescript-eslint';

export default tseslint.config(
  // ... the rest of your config ...
  {
    files: ['**/*.{ts,tsx,mts,cts}'],
    rules: {
      'no-undef': 'off',
    },
  },
);

Legacy Config

.eslintrc.js

module.exports = {
  // ... the rest of your config ...
  overrides: [
    {
      files: ['*.ts', '*.mts', '*.cts', '*.tsx'],
      rules: {
        'no-undef': 'off',
      },
    },
  ],
};

如果你选择保留 ESLint no-undef lint 规则，则可以使用 在 ESLint 配置中手动定义允许的 globals 集，和/或可以使用 预定义环境 (env) 配置 之一。

¥If you choose to leave on the ESLint no-undef lint rule, you can manually define the set of allowed globals in your ESLint config, and/or you can use one of the pre-defined environment (env) configurations.

我收到有关声明全局变量的 @typescript-eslint/no-namespace 和/或 no-var 规则的错误

¥I get errors from the @typescript-eslint/no-namespace and/or no-var rules about declaring global variables

TypeScript 中用于声明全局变量存在的两种常见解决方案包括：

¥Two common solutions in TypeScript for declaring the existence of a global variable include:

• declare global 带有 var，这违反了 no-var：

  ¥declare global with a var, which violates no-var:

  declare global {
    var myValue: string;
    // Unexpected var, use let or const instead. eslint (no-var)
  }
  
  myValue;

• declare namespace globalThis，违反 @typescript-eslint/no-namespace：

  ¥declare namespace globalThis, which violates @typescript-eslint/no-namespace:

  declare namespace globalThis {
    // ES2015 module syntax is preferred over namespaces. eslint (@typescript-eslint/no-namespace)
    let myValue: string;
  }
  
  globalThis.myValue;

通常不鼓励使用全局变量。如果可能，最好完全避免声明全局变量。

¥Using global variables is generally discouraged. If possible, it's best to avoid declaring globals altogether.

如果你绝对必须使用这两种策略之一，那么你可以使用 ESLint 配置注释 根据需要禁用规则。例如：

¥If you absolutely must use one of the two strategies, then you can use an ESLint configuration comment to disable rules as needed. For example:

declare global {
  // eslint-disable-next-line no-var -- Provided by an old third-party integration.
  var myValue: string;
}

提示

每当你需要禁用 ESLint 规则时，最好包含一条说明原因的注释。

¥Whenever you need to disable an ESLint rule, it's best to include an informative comment explaining why.

有关支持这些用例的 typescript-eslint 的讨论，请参阅 #9582 和 #7941。

¥See #9582 and #7941 for discussions around typescript-eslint supporting these use cases.

我可以将 ESLint 的 --cache 与 typescript-eslint 一起使用吗？

¥Can I use ESLint's --cache with typescript-eslint?

ESLint 的 --cache 选项 基于每个文件进行缓存。你可以使用它，但它只能可靠地用于无类型规则 - 即使如此，也并非总是如此。

¥ESLint's --cache option caches on a per-file basis. You can use it, but it will only work reliably for untyped rules -- and even then, not always.

任何检查跨文件逻辑的 ESLint 规则（包括来自 eslint-plugin-import 的许多规则）都会创建跨文件依赖。在实践中，类型化 lint 规则 几乎总是依赖于跨文件的类型。ESLint 的缓存不考虑那些跨文件依赖。

¥Any ESLint rule that checks logic across files, including many rules from eslint-plugin-import, creates cross-file dependencies. Typed lint rules almost always have dependencies on types across files in practice. ESLint's caching doesn't account for those cross-file dependencies.

我们不建议使用 --cache。

¥We don't recommend using --cache.