ESLint 新手入门

ESLint 是一个用于识别和报告在 ECMAScript/JavaScript 代码中发现的模式的工具，其目标是使代码更加一致并避免错误。

¥ESLint is a tool for identifying and reporting on patterns found in ECMAScript/JavaScript code, with the goal of making code more consistent and avoiding bugs.

ESLint 是完全插件化的。每条规则都是一个插件，你可以在运行时添加更多。你还可以添加社区插件、配置和解析器来扩展 ESLint 的功能。

¥ESLint is completely pluggable. Every single rule is a plugin and you can add more at runtime. You can also add community plugins, configurations, and parsers to extend the functionality of ESLint.

先决条件

¥Prerequisites

要使用 ESLint，你必须安装并构建 Node.js（^18.18.0、^20.9.0 或 >=21.1.0）并支持 SSL。（如果你使用的是官方 Node.js 发行版，则始终内置 SSL。）

¥To use ESLint, you must have Node.js (^18.18.0, ^20.9.0, or >=21.1.0) installed and built with SSL support. (If you are using an official Node.js distribution, SSL is always built in.)

快速开始

¥Quick start

你可以使用以下命令安装和配置 ESLint：

¥You can install and configure ESLint using this command:

npm

npm init @eslint/config@latest
1

yarn

yarn create @eslint/config
1

pnpm

pnpm create @eslint/config@latest
1

bun

bun create @eslint/config@latest
1

如果你想使用托管在 npm 上的特定可共享配置，你可以使用 --config 选项并指定包名称：

¥If you want to use a specific shareable config that is hosted on npm, you can use the --config option and specify the package name:

npm

# use `eslint-config-xo` shared config - npm 7+
npm init @eslint/config@latest -- --config eslint-config-xo
1
2

yarn

# use `eslint-config-xo` shared config - npm 7+
yarn create @eslint/config -- --config eslint-config-xo
1
2

pnpm

# use `eslint-config-xo` shared config - npm 7+
pnpm create @eslint/config@latest -- --config eslint-config-xo
1
2

bun

# use `eslint-config-xo` shared config - npm 7+
bun create @eslint/config@latest -- --config eslint-config-xo
1
2

注意：npm init @eslint/config 假定你已经有 package.json 文件。如果没有，请确保事先运行 npm init 或 yarn init。

¥Note: npm init @eslint/config assumes you have a package.json file already. If you don’t, make sure to run npm init or yarn init beforehand.

之后，你可以在任何文件或目录上运行 ESLint，如下所示：

¥After that, you can run ESLint on any file or directory like this:

npm

npx eslint yourfile.js 
1

yarn

yarn dlx eslint yourfile.js 
1

pnpm

pnpm dlx eslint yourfile.js 
1

bun

bunx eslint yourfile.js 
1

配置

¥Configuration

注意：如果你使用的是 9.0.0 之前的版本，请参阅迁移指南。

¥Note: If you are coming from a version before 9.0.0 please see the migration guide.

当你运行 npm init @eslint/config 时，系统会询问你一系列问题，以确定你如何使用 ESLint 以及应包含哪些选项。回答这些问题后，你将在目录中创建一个 eslint.config.js（或 eslint.config.mjs）文件。

¥When you run npm init @eslint/config, you’ll be asked a series of questions to determine how you’re using ESLint and what options should be included. After answering these questions, you’ll have an eslint.config.js (or eslint.config.mjs) file created in your directory.

例如，其中一个问题是 “你的代码在哪里运行？” 如果你选择 “浏览器”，那么你的配置文件将包含 Web 浏览器中全局变量的定义。这是一个例子：

¥For example, one of the questions is “Where does your code run?” If you select “Browser” then your configuration file will contain the definitions for global variables found in web browsers. Here’s an example:

import { defineConfig } from "eslint/config";
import globals from "globals";
import js from "@eslint/js";

export default defineConfig([
	{ files: ["**/*.js"], languageOptions: { globals: globals.browser } },
	{ files: ["**/*.js"], plugins: { js }, extends: ["js/recommended"] },
]);
1
2
3
4
5
6
7
8

"js/recommended" 配置确保所有在规则页面上标记为推荐的规则都将被启用。或者，你可以通过在 npmjs.com 上搜索 “eslint-config” 来使用其他人创建的配置。除非你从共享配置扩展或在配置中明确打开规则，否则 ESLint 不会检查你的代码。

¥The "js/recommended" configuration ensures all of the rules marked as recommended on the rules page will be turned on. Alternatively, you can use configurations that others have created by searching for “eslint-config” on npmjs.com. ESLint will not lint your code unless you extend from a shared configuration or explicitly turn rules on in your configuration.

你可以通过使用 rules 键定义新对象来单独配置规则，如下例所示：

¥You can configure rules individually by defining a new object with a rules key, as in this example:

import { defineConfig } from "eslint/config";
import js from "@eslint/js";

export default defineConfig([
	{ files: ["**/*.js"], plugins: { js }, extends: ["js/recommended"] },

	{
		rules: {
			"no-unused-vars": "warn",
			"no-undef": "warn",
		},
	},
]);
1
2
3
4
5
6
7
8
9
10
11
12
13

名称 "no-unused-vars" 和 "no-undef" 是 ESLint 中规则的名称。第一个值是规则的错误级别，可以是以下值之一：

¥The names "no-unused-vars" and "no-undef" are the names of rules in ESLint. The first value is the error level of the rule and can be one of these values:

“off” 或 0 - 关闭规则

¥"off" or 0 - turn the rule off
“warn” 或 1 - 将规则作为警告打开（不影响退出代码）

¥"warn" or 1 - turn the rule on as a warning (doesn’t affect exit code)
“error” 或 2 - 打开规则作为错误（退出代码将为 1）

¥"error" or 2 - turn the rule on as an error (exit code will be 1)

三个错误级别允许你细粒度地控制 ESLint 如何应用规则（有关更多配置选项和详细信息，请参阅配置文档）。

¥The three error levels allow you fine-grained control over how ESLint applies rules (for more configuration options and details, see the configuration docs).

全局安装

¥Global Install

也可以使用 npm install eslint --global 在全局而不是局部安装 ESLint。但是，不推荐这样做，如果你全局安装 ESLint，你使用的任何插件或可共享配置仍必须安装在局部。

¥It is also possible to install ESLint globally, rather than locally, using npm install eslint --global. However, this is not recommended, and any plugins or shareable configs that you use must still be installed locally if you install ESLint globally.

手动设置

¥Manual Set Up

你还可以在项目中手动设置 ESLint。

¥You can also manually set up ESLint in your project.

Important

如果你使用 pnpm，请确保创建一个至少具有以下设置的 .npmrc 文件：

¥If you are using pnpm, be sure to create a .npmrc file with at least the following settings:

auto-install-peers=true
node-linker=hoisted
1
2

这可确保 pnpm 以与 npm 更兼容的方式安装依赖，并且不太可能产生错误。

¥This ensures that pnpm installs dependencies in a way that is more compatible with npm and is less likely to produce errors.

在开始之前，你必须已经有一个 package.json 文件。如果不这样做，请确保事先运行 npm init 或 yarn init 来创建文件。

¥Before you begin, you must already have a package.json file. If you don’t, make sure to run npm init or yarn init to create the file beforehand.

在你的项目中安装 ESLint 包：

¥Install the ESLint packages in your project:

npm

npm install --save-dev eslint @eslint/js
1

yarn

yarn add --dev eslint @eslint/js
1

pnpm

pnpm add --save-dev eslint @eslint/js
1

bun

bun add --dev eslint @eslint/js
1

添加 eslint.config.js 文件：

¥Add an eslint.config.js file:
```
# Create JavaScript configuration file
touch eslint.config.js
1
2
```

将配置添加到 eslint.config.js 文件。请参阅配置 ESLint 文档了解如何添加规则、自定义配置、插件等。

¥Add configuration to the eslint.config.js file. Refer to the Configure ESLint documentation to learn how to add rules, custom configurations, plugins, and more.

import { defineConfig } from "eslint/config";
import js from "@eslint/js";

export default defineConfig([
	{
		files: ["**/*.js"],
		plugins: {
			js,
		},
		extends: ["js/recommended"],
		rules: {
			"no-unused-vars": "warn",
			"no-undef": "warn",
		},
	},
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

使用 ESLint CLI 进行代码检查：

¥Lint code using the ESLint CLI:

npm

npx eslint project-dir/ file.js 
1

yarn

yarn dlx eslint project-dir/ file.js 
1

pnpm

pnpm dlx eslint project-dir/ file.js 
1

bun

bunx eslint project-dir/ file.js 
1

有关可用 CLI 选项的更多信息，请参阅命令行接口。

¥For more information on the available CLI options, refer to Command Line Interface.

下一步

¥Next Steps

了解 ESLint 的高级配置。

¥Learn about advanced configuration of ESLint.
熟悉命令行选项。

¥Get familiar with the command line options.
探索 ESLint 集成到其他工具，如编辑器、构建系统等。

¥Explore ESLint integrations into other tools like editors, build systems, and more.
找不到合适的规则？制作你自己的自定义规则。

¥Can’t find just the right rule? Make your own custom rule.
贡献让 ESLint 变得更好。

¥Make ESLint even better by contributing.