忽略文件

你可以通过以下方式指定一个或多个通配符模式，在 linting 时配置 ESLint 忽略某些文件和目录：

在你的 eslint.config.js 文件内部。
在命令行中使用 --ignore-pattern。

忽略文件

🌐 Ignore Files

在你的 eslint.config.js 文件中，你可以使用 globalIgnores() 辅助函数来指示要忽略的文件模式。示例如下：

🌐 In your eslint.config.js file, you can use the globalIgnores() helper function to indicate patterns of files to be ignored. Here’s an example:

// eslint.config.js
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([globalIgnores([".config/*"])]);
1
2
3
4

此配置指定应忽略 .config 目录中的所有文件。此模式添加在默认模式之后，默认模式是 ["**/node_modules/", ".git/"]。

🌐 This configuration specifies that all of the files in the .config directory should be ignored. This pattern is added after the default patterns, which are ["**/node_modules/", ".git/"].

默认情况下，ESLint 会检查与模式 **/*.js、**/*.cjs 和 **/*.mjs 匹配的文件。如果你不希望 ESLint 检查这些文件，可以使用 globalIgnores() 忽略它们：

🌐 By default, ESLint lints files that match the patterns **/*.js, **/*.cjs, and **/*.mjs. You can ignore them with globalIgnores() if you don’t want ESLint to lint these files:

// eslint.config.js
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([
	globalIgnores(["**/*.js", "**/*.cjs", "**/*.mjs"]),
]);
1
2
3
4
5
6

当在 files 属性中指定非 JS 文件时，ESLint 仍会对符合默认模式的文件进行检查。要仅检查在 files 属性中指定的文件，必须忽略默认的文件模式：

🌐 When non-JS files are specified in the files property, ESLint still lints files that match the default patterns. To lint only the files specified in the files property, you must ignore the default file patterns:

// eslint.config.js
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([
	globalIgnores(["**/*.js", "**/*.cjs", "**/*.mjs"]),
	{
		files: ["**/*.ts"],
		ignores: [".config/**"],
		rules: {
			/* ... */
		},
	},
]);
1
2
3
4
5
6
7
8
9
10
11
12
13

你也可以使用 --ignore-pattern 在命令行中忽略文件，例如：

🌐 You can also ignore files on the command line using --ignore-pattern, such as:

npm

npx eslint . --ignore-pattern '.config/*' 
1

yarn

yarn dlx eslint . --ignore-pattern '.config/*' 
1

pnpm

pnpm dlx eslint . --ignore-pattern '.config/*' 
1

bun

bunx eslint . --ignore-pattern '.config/*' 
1

忽略目录

🌐 Ignore Directories

忽略目录的方式与忽略文件相同，通过将模式传递给 globalIgnores() 辅助函数。例如，以下内容将整个 .config 目录忽略（意味着文件搜索根本不会进入该目录）：

🌐 Ignoring directories works the same way as ignoring files, by passing a pattern to the globalIgnores() helper function. For example, the following ignores the .config directory as a whole (meaning file search will not traverse into it at all):

// eslint.config.js
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([globalIgnores([".config/"])]);
1
2
3
4

与 .gitignore 不同，像 .config 这样的忽略模式只会忽略与配置文件位于同一目录下的 .config 目录。如果你想递归地忽略所有名为 .config 的目录，你需要使用 **/.config/，如本例所示：

🌐 Unlike .gitignore, an ignore pattern like .config will only ignore the .config directory in the same directory as the configuration file. If you want to recursively ignore all directories named .config, you need to use **/.config/, as in this example:

// eslint.config.js
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([globalIgnores(["**/.config/"])]);
1
2
3
4

取消忽略文件和目录

🌐 Unignore Files and Directories

你也可以取消忽略那些被之前的模式（包括默认模式）忽略的文件和目录。例如，这个配置取消忽略了 node_modules/mylibrary：

🌐 You can also unignore files and directories that are ignored by previous patterns, including the default patterns. For example, this config unignores node_modules/mylibrary:

// eslint.config.js
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([
	globalIgnores([
		"!node_modules/", // unignore `node_modules/` directory
		"node_modules/*", // ignore its content
		"!node_modules/mylibrary/", // unignore `node_modules/mylibrary` directory
	]),
]);
1
2
3
4
5
6
7
8
9
10

如果你想忽略一个目录，但保留特定的文件或子目录，则必须使用忽略模式 directory/**/* 而不是 directory/**。模式 directory/** 会忽略整个目录及其内容，因此遍历将完全跳过该目录，并且你无法取消忽略其中的任何内容。

🌐 If you’d like to ignore a directory except for specific files or subdirectories, then the ignore pattern directory/**/* must be used instead of directory/**. The pattern directory/** ignores the entire directory and its contents, so traversal will skip over the directory completely and you cannot unignore anything inside.

例如，build/** 会忽略目录 build 及其内容，而 build/**/* 只会忽略其内容。如果你想忽略 build 目录中的所有内容，除了 build/test.js，你需要创建如下配置：

🌐 For example, build/** ignores directory build and its contents, whereas build/**/* ignores only its contents. If you’d like to ignore everything in the build directory except for build/test.js, you’d need to create a config like this:

// eslint.config.js
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([
	globalIgnores([
		"build/**/*", // ignore all contents in and under `build/` directory but not the `build/` directory itself
		"!build/test.js", // unignore `!build/test.js`
	]),
]);
1
2
3
4
5
6
7
8
9

如果你想忽略某个目录但保留目录下任意级别的特定文件，你还应该确保子目录不会被忽略。请注意，虽然以 / 结尾的模式只匹配目录，但不以 / 结尾的模式既匹配文件也匹配目录，因此不可能写出只忽略文件的单个模式，但你可以通过两个模式实现：一个用于忽略所有内容，另一个用于取消忽略子目录。

🌐 If you’d like to ignore a directory except for specific files at any level under the directory, you should also ensure that subdirectories are not ignored. Note that while patterns that end with / only match directories, patterns that don’t end with / match both files and directories so it isn’t possible to write a single pattern that only ignores files, but you can achieve this with two patterns: one to ignore all contents and another to unignore subdirectories.

例如，此配置会忽略 build 目录及其下的所有文件，但在任何层级下名为 test.js 的文件除外：

🌐 For example, this config ignores all files in and under build directory except for files named test.js at any level:

// eslint.config.js
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([
	globalIgnores([
		"build/**/*", // ignore all contents in and under `build/` directory but not the `build/` directory itself
		"!build/**/*/", // unignore all subdirectories
		"!build/**/test.js", // unignore `test.js` files
	]),
]);
1
2
3
4
5
6
7
8
9
10

如果你想在仍然对特定文件或目录进行 lint 的情况下忽略 ESLint 的默认文件模式（**/*.js、**/*.cjs 和 **/*.mjs），可以使用否定模式来取消忽略它们：

🌐 If you want to ignore ESLint’s default file patterns (**/*.js, **/*.cjs, and **/*.mjs) while still linting specific files or directories, you can use negative patterns to unignore them:

// eslint.config.js
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([
	globalIgnores(["**/*.js", "**/*.cjs", "**/*.mjs", "!**/src/**/*.js"]),
]);
1
2
3
4
5
6

此配置会忽略所有与默认模式匹配的文件，除了位于 src 目录中的 JavaScript 文件。

🌐 This configuration ignores all files matching the default patterns except for JavaScript files located within src directories.

你也可以在命令行上使用 --ignore-pattern 取消忽略文件，例如：

🌐 You can also unignore files on the command line using --ignore-pattern, such as:

npm

npx eslint . --ignore-pattern '!node_modules/' 
1

yarn

yarn dlx eslint . --ignore-pattern '!node_modules/' 
1

pnpm

pnpm dlx eslint . --ignore-pattern '!node_modules/' 
1

bun

bunx eslint . --ignore-pattern '!node_modules/' 
1

通配符模式解析

🌐 Glob Pattern Resolution

通配符模式的评估方式取决于它们所在的位置以及它们的使用方式：

🌐 How glob patterns are evaluated depends on where they are located and how they are used:

在 eslint.config.js 文件中使用 globalIgnores() 时，通配符模式是相对于 eslint.config.js 文件进行评估的。
当在使用 --config 命令行选项指定的备用配置文件中使用 globalIgnores() 时，通配符模式是相对于当前工作目录进行评估的。
使用 --ignore-pattern 时，通配符模式是相对于当前工作目录进行评估的。

命名全局忽略配置

🌐 Name the Global Ignores Config

默认情况下，globalIgnores() 会为表示你忽略项的配置分配一个名称。你可以通过向 globalIgnores() 提供第二个参数来覆盖此名称，该参数是你想使用的名称，而不是默认名称：

🌐 By default, globalIgnores() will assign a name to the config that represents your ignores. You can override this name by providing a second argument to globalIgnores(), which is the name you’d like to use instead of the default:

// eslint.config.js
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([
	globalIgnores(["build/**/*"], "Ignore Build Directory"),
]);
1
2
3
4
5
6

这个例子中的 "Ignore Build Directory" 字符串是为全局忽略创建的配置名称。这对于调试目的很有用。

🌐 The "Ignore Build Directory" string in this example is the name of the config created for the global ignores. This is useful for debugging purposes.

忽略的文件警告

🌐 Ignored File Warnings

当你将目录传给 ESLint CLI 时，文件和目录会被静默忽略。如果你将一个特定的文件传给 ESLint，那么 ESLint 会创建一个警告，提示该文件被跳过。例如，假设你有一个 eslint.config.js 文件，看起来是这样的：

🌐 When you pass directories to the ESLint CLI, files and directories are silently ignored. If you pass a specific file to ESLint, then ESLint creates a warning that the file was skipped. For example, suppose you have an eslint.config.js file that looks like this:

// eslint.config.js
import { defineConfig, globalIgnores } from "eslint/config";

export default defineConfig([globalIgnores(["foo.js"])]);
1
2
3
4

然后你运行：

🌐 And then you run:

npm

npx eslint foo.js 
1

yarn

yarn dlx eslint foo.js 
1

pnpm

pnpm dlx eslint foo.js 
1

bun

bunx eslint foo.js 
1

你会看到这个警告：

🌐 You’ll see this warning:

foo.js
  0:0  warning  File ignored because of a matching ignore pattern. Use "--no-ignore" to disable file ignore settings or use "--no-warn-ignored" to suppress this warning.

✖ 1 problem (0 errors, 1 warning)
1
2
3
4

出现此消息是因为 ESLint 不确定你是否真的想要对该文件进行 lint。正如消息所示，你可以使用 --no-ignore 来省略使用忽略规则。

🌐 This message occurs because ESLint is unsure if you wanted to actually lint the file or not. As the message indicates, you can use --no-ignore to omit using the ignore rules.

包含 `.gitignore` 文件

🌐 Include .gitignore Files

如果你想从 .gitignore 文件或任何其他具有 gitignore 风格模式的文件中包含模式，你可以使用 includeIgnoreFile 工具。

🌐 If you want to include patterns from a .gitignore file or any other file with gitignore-style patterns, you can use the includeIgnoreFile utility.

// eslint.config.js

import { defineConfig, includeIgnoreFile } from "eslint/config";
import { fileURLToPath } from "node:url";

const gitignorePath = fileURLToPath(new URL(".gitignore", import.meta.url));

export default defineConfig([
	includeIgnoreFile(gitignorePath, { gitignoreResolution: true }),
	{
		// your overrides
	},
]);
1
2
3
4
5
6
7
8
9
10
11
12
13

这会自动加载指定的文件，并将 gitignore 风格的模式转换为包含 ignores 全局模式的配置对象。{ gitignoreResolution: true } 选项确保模式将相对于指定文件的位置进行解析。

🌐 This automatically loads the specified file and translates gitignore-style patterns into a config object containing ignores glob patterns. The { gitignoreResolution: true } option ensures that patterns will be interpreted relative to the location of the specified file.

也可以提供一个忽略文件路径数组：

🌐 An array of ignore file paths can also be provided:

// eslint.config.js

import { defineConfig, includeIgnoreFile } from "eslint/config";
import { fileURLToPath } from "node:url";

const rootGitignorePath = fileURLToPath(new URL(".gitignore", import.meta.url));
const nestedGitignorePath = fileURLToPath(
	new URL("some/other/folder/.gitignore", import.meta.url),
);

export default defineConfig([
	includeIgnoreFile([rootGitignorePath, nestedGitignorePath], {
		gitignoreResolution: true,
	}),
	{
		// your overrides
	},
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

在这种情况下，将返回一个配置对象数组。

🌐 In this case, an array of config objects will be returned.

包括其他忽略文件

🌐 Include other ignore files

如果省略 { gitignoreResolution: true }，或者指定了 { gitignoreResolution: false" }，includeIgnoreFile() 将会根据 ESLint 配置文件的位置来解释忽略模式。

🌐 If { gitignoreResolution: true } is omitted, or if { gitignoreResolution: false" } is specified, includeIgnoreFile() will interpret the ignore patterns relative to the location of the ESLint config file.

// eslint.config.js

import { defineConfig, includeIgnoreFile } from "eslint/config";
import { fileURLToPath } from "node:url";

const eslintIgnorePath = fileURLToPath(
	new URL("eslint-ignore-patterns", import.meta.url),
);

export default defineConfig([
	includeIgnoreFile(eslintIgnorePath),
	{
		// your overrides
	},
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

相比之下，.gitignore 文件的规定是忽略模式应相对于 .gitignore 文件本身的位置来解释。因此，{ gitignoreResolution: true }，它告诉 includeIgnoreFile() 要匹配这一行为，在包含来自 .gitignore 文件的忽略模式时应始终使用。

🌐 By contrast, .gitignore files are specified such that the ignore patterns should be interpreted relative to the location of the .gitignore file itself. Therefore, { gitignoreResolution: true }, which tells includeIgnoreFile() to match this behavior, should always be used when including ignore patterns from .gitignore files.

自定义输出配置的名称

🌐 Customize name of output configs

默认情况下，includeIgnoreFile() 会给表示你忽略项的配置分配一个名称。你可以通过在 includeIgnoreFile() 的第二个参数中提供它来覆盖这个名称：

🌐 By default, includeIgnoreFile() will assign a name to the config that represents your ignores. You can override this name by providing it in the second argument to includeIgnoreFile():

// eslint.config.js

import { defineConfig, includeIgnoreFile } from "eslint/config";
import { fileURLToPath } from "node:url";

const gitignorePath = fileURLToPath(new URL(".gitignore", import.meta.url));

export default defineConfig([
	includeIgnoreFile(gitignorePath, {
		gitignoreResolution: true,
		name: "Imported .gitignore patterns",
	}),
	{
		// your overrides
	},
]);
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

忽略文件

忽略文件

npm

yarn

pnpm

bun

忽略目录

取消忽略文件和目录

npm

yarn

pnpm

bun

通配符模式解析

命名全局忽略配置

忽略的文件警告

npm

yarn

pnpm

bun

包含 .gitignore 文件

包括其他忽略文件

自定义输出配置的名称

包含 `.gitignore` 文件