no-unused-vars

Disallow unused variables.

✅

在 ESLint 配置 中扩展"plugin:@typescript-eslint/recommended" 可启用此规则。

🧱

This is an "extension" rule that replaces a core ESLint rule to work with TypeScript. See Rules > Extension Rules.

This rule extends the base no-unused-vars rule from ESLint core. 它增加了对 TypeScript 功能（例如类型）的支持。

¥It adds support for TypeScript features, such as types.

如何使用

Flat Config

eslint.config.mjs

export default tseslint.config({
  rules: {
    // Note: you must disable the base rule as it can report incorrect errors
    "no-unused-vars": "off",
    "@typescript-eslint/no-unused-vars": "error"
  }
});

Legacy Config

.eslintrc.cjs

module.exports = {
  "rules": {
    // Note: you must disable the base rule as it can report incorrect errors
    "no-unused-vars": "off",
    "@typescript-eslint/no-unused-vars": "error"
  }
};

在线运行试试这个规则 ↗

选项

See eslint/no-unused-vars's options.

¥Options

常见问题

¥FAQs

此规则与 TypeScript 相比有什么好处？

¥What benefits does this rule have over TypeScript?

TypeScript 提供 noUnusedLocals 和 noUnusedParameters 编译器选项，可分别报告未使用的局部变量或参数的错误。如果你不想设置 ESLint 和 typescript-eslint，那么这些编译器选项可以很方便地使用。然而：

¥TypeScript provides noUnusedLocals and noUnusedParameters compiler options that can report errors on unused local variables or parameters, respectively. Those compiler options can be convenient to use if you don't want to set up ESLint and typescript-eslint. However:

• 这些 lint 规则比 TypeScript 的编译器选项更可配置。

  ¥These lint rules are more configurable than TypeScript's compiler options.

  • 例如，varsIgnorePattern 选项 可以自定义始终允许豁免的名称。TypeScript 将其豁免硬编码为以 _ 开头的名称。如果你想要模拟 TypeScript 风格的以 _ 开头的豁免名称，你可以使用此配置（这也包括错误）：

    ¥For example, the varsIgnorePattern option can customize what names are always allowed to be exempted. TypeScript hardcodes its exemptions to names starting with _. If you would like to emulate the TypeScript style of exempting names starting with _, you can use this configuration (this includes errors as well):

    {
      "rules": {
        "@typescript-eslint/no-unused-vars": [
          "error",
          {
            "args": "all",
            "argsIgnorePattern": "^_",
            "caughtErrors": "all",
            "caughtErrorsIgnorePattern": "^_",
            "destructuredArrayIgnorePattern": "^_",
            "varsIgnorePattern": "^_",
            "ignoreRestSiblings": true
          }
        ]
      }
    }

• ESLint 可以配置 在行、文件和文件夹中。TypeScript 编译器选项链接到其 TSConfig 文件。

  ¥ESLint can be configured within lines, files, and folders. TypeScript compiler options are linked to their TSConfig file.

• 许多项目将 TypeScript 报告的错误配置为比 ESLint 投诉更积极地阻止构建。在未使用的变量上阻塞构建可能会很不方便。

  ¥Many projects configure TypeScript's reported errors to block builds more aggressively than ESLint complaints. Blocking builds on unused variables can be inconvenient.

我们通常建议使用 @typescript-eslint/no-unused-vars 来标记未使用的本地变量和参数，而不是 TypeScript。

¥We generally recommend using @typescript-eslint/no-unused-vars to flag unused locals and parameters instead of TypeScript.

提示

即使项目中未启用 noUnusedLocals 和 noUnusedParameters，VS Code 等编辑器通常仍会 "灰色" 未使用的变量。

¥Editors such as VS Code will still generally "grey out" unused variables even if noUnusedLocals and noUnusedParameters are not enabled in a project.

另请参阅 ESLint 提供的类似规则：

¥Also see similar rules provided by ESLint:

• no-unused-private-class-members

• no-unused-labels

为什么此规则报告仅用于类型的变量？

¥Why does this rule report variables used only for types?

此规则在确定变量是否被使用时不计算仅类型的使用。仅将变量声明为类型会增加代码和运行时的复杂性。变量在运行时从未实际使用过。它们可能会误导代码读者。

¥This rule does not count type-only uses when determining whether a variable is used. Declaring variables only to use them for types adds code and runtime complexity. The variables are never actually used at runtime. They can be misleading to readers of the code.

typeof Variables

例如，如果变量仅用于 typeof，则此规则将报告：

¥For example, if a variable is only used for typeof, this rule will report:

const box = {
  //  ~~~
  //  'box' is assigned a value but only used as a type.
  value: 123,
};

export type Box = typeof box;

Open in Playground

相反，直接写出类型通常更干净，代码也更少：

¥Instead, it's often cleaner and less code to write out the types directly:

export interface Box {
  value: number;
}

Open in Playground

Zod Schemas

例如，如果 Zod 模式变量仅用于 typeof，则此规则将报告：

¥For example, if a Zod schema variable is only used for typeof, this rule will report:

import { z } from 'zod';

const schema = z.object({
  //  ~~~~~~
  //  'schema' is assigned a value but only used as a type.
  value: z.number(),
});

export type Box = z.infer<typeof schema>;

Open in Playground

相反，直接写出类型通常更干净，代码也更少：

¥Instead, it's often cleaner and less code to write out the types directly:

export interface Box {
  value: number;
}

Open in Playground

如果你发现自己只为类型编写运行时值，请考虑重构代码以直接声明类型。

¥If you find yourself writing runtime values only for types, consider refactoring your code to declare types directly.

'## 资源'

• 规则源码
• 测试源码

^{Taken with ❤️ from ESLint core.}