# @eslint/config-array 中文文档

规范地址：https://npmcn.com/package/%40eslint/config-array/

版本：0\.23\.5
npm 元数据更新时间：2026-04-08T09:22:38.084Z
中文译文更新时间：2026-11-05T14:46:32.348Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40eslint/config-array
原文对照：https://npmcn.com/package/%40eslint/config-array/?lang=original
项目主页：https://github.com/eslint/rewrite/tree/main/packages/config-array#readme
源码仓库：https://github.com/eslint/rewrite

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：329 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| ^22\.13\.0 \|\| \>=24
- 运行依赖：3 个
- 首次发布：2024-05-30T20:40:31.865Z
- 最新版本发布：2026-04-08T09:22:37.796Z
- 近 30 天下载量：517948465（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：20（近 12 个月 8 个）

## 中文简介

通用 glob 配置匹配 .

## 安装

```sh
npm install @eslint/config-array
```

也可以使用：`pnpm add @eslint/config-array`、`yarn add @eslint/config-array`、`bun add @eslint/config-array`

## README

# 配置矩阵

## 说明

配置阵列是管理配置的一种方式,这种配置基于文件名的 glob 模式匹配. 每个配置阵列包含根据文件名确定任何文件正确配置所需的信息.

**说明:** 这是一个通用软件包,可以在ESLint之外使用. 它没有包含ESLint特定功能.

## 安装

对于节点和相容运行时间:

```shell
npm install @eslint/config-array
# or
yarn add @eslint/config-array
# or
pnpm install @eslint/config-array
# or
bun add @eslint/config-array
```

对于德诺:

```shell
deno add @eslint/config-array
```

## 背景情况

基本的想法是,所有配置,包括覆被,都可以由单个数组来表示,其中数组中的每个项目都是一个配置对象. 配置对象出现在数组后面, 覆盖在数组前面出现的配置对象 。 您可以通过翻转数组中的所有配置对象来计算给定文件的配置, 以找到匹配文件名的对象 。 匹配是通过在 `files` 财务报告和审定财务报表 `ignores` 每个配置对象的属性。 举个例子:

```js
export default [
    // match all JSON files
    {
        name: "JSON Handler",
        files: ["**/*.json"],
        handler: jsonHandler,
    },

    // match only package.json
    {
        name: "package.json Handler",
        files: ["package.json"],
        handler: packageJsonHandler,
    },
];
```

在这个例子中,有两个配置对象:第一个匹配所有目录中的所有 JSON 文件,第二个匹配只是 `package.json` 在基础路径目录中(所有 globs 被评价为相对于一个可以指定的基础路径). 当您获取配置时 `foo.json`只有第一个配置对象匹配 `handler` 等于 `jsonHandler`; 当您获取配置时 `package.json`, (中文(简体) ), `handler` 等于 `packageJsonHandler` (因为两个配置对象都匹配,第二个获胜).

## 使用量

首先导入 `ConfigArray` 构造器 :

```js
import { ConfigArray } from "@eslint/config-array";

// or using CommonJS

const { ConfigArray } = require("@eslint/config-array");
```

当你创建一个新的实例 `ConfigArray`,您必须在两个参数中通过:一组配置和一个选项对象。 配置的阵列最有可能从配置文件中读取,所以这里有一个典型的例子:

```js
import path from "node:path";
import { pathToFileURL } from "node:url";
import { ConfigArray } from "@eslint/config-array";

const configFilename = path.resolve(process.cwd(), "my.config.js");
const { default: rawConfigs } = await import(pathToFileURL(configFilename));

const configs = new ConfigArray(rawConfigs, {
    // the path to match filenames from
    basePath: process.cwd(),

    // additional items in each config
    schema: mySchema,
});
```

此示例在对象或数组中读取: `my.config.js` 传入 `ConfigArray` 构造器作为第一个参数. 第二个参数是一个指定对象 `basePath` (目录中 `my.config.js` (已找到)和a `schema` 以定义配置对象之外的额外属性 `files`, (中文(简体) ), `ignores`, (中文(简体) ), `basePath`,以及 `name`。 。 。 .

### 指定外观

这个 `schema` 在配置对象中,您需要使用额外的属性。 schema 是一个对象,它遵循一个 [`ObjectSchema`](https://npmjs.com/package/@eslint/object-schema)。这个计划既规定了验证规则,也规定了合并规则 `ConfigArray` 当有多个匹配时,实例需要组合配置。 举个例子:

```js
const configFilename = path.resolve(process.cwd(), "my.config.js");
const { default: rawConfigs } = await import(pathToFileURL(configFilename));

const mySchema = {
    // define the handler key in configs
    handler: {
        required: true,
        merge(a, b) {
            return b ?? a;
        },
        validate(value) {
            if (typeof value !== "function") {
                throw new TypeError("Function expected.");
            }
        },
    },
};

const configs = new ConfigArray(rawConfigs, {
    // the path to match filenames from
    basePath: process.cwd(),

    // additional item schemas in each config
    schema: mySchema,

    // additional config types supported (default: [])
    extraConfigTypes: ["array", "function"],
});
```

### 配置矩阵

配置阵列可以是多维的,因此一个配置阵列有可能包含另一个配置阵列,当 `extraConfigTypes` 包含 `"array"`,例如:

```js
export default [
    // JS config
    {
        files: ["**/*.js"],
        handler: jsHandler,
    },

    // JSON configs
    [
        // match all JSON files
        {
            name: "JSON Handler",
            files: ["**/*.json"],
            handler: jsonHandler,
        },

        // match only package.json
        {
            name: "package.json Handler",
            files: ["package.json"],
            handler: packageJsonHandler,
        },
    ],

    // filename must match function
    {
        files: [filePath => filePath.endsWith(".md")],
        handler: markdownHandler,
    },

    // filename must match all patterns in subarray
    {
        files: [["*.test.*", "*.js"]],
        handler: jsTestHandler,
    },

    // filename must not match patterns beginning with !
    {
        name: "Non-JS files",
        files: ["!*.js"],
        settings: {
            js: false,
        },
    },

    // specific settings for files inside `src` directory
    {
        name: "Source files",
        basePath: "src",
        files: ["**/*"],
        settings: {
            source: true,
        },
    },
];
```

在这个例子中,阵列同时包含配置对象和一个配置阵列. 当一个配置阵列实现正态化(见下文细节)时,它被平整,所以仅保留了配置对象. 然而,评价的顺序保持不变.

如果 `files` 数组包含一个函数,然后该函数随文件的路径被调用。 该功能预计将返回 `true` 如果有一个匹配和 `false` 如果不是的话。 (本节) `ignores` 数组也可以包含函数. )

如果 `files` 数组包含一个字符串和函数的数组,然后所有图案必须相匹配才能匹配配置。 在上述例子中 `*.test.*` 财务报告和审定财务报表 `*.js` 要使用配置对象,必须匹配.

如果文件数组中的图案开始 `!` 然后它排除了这种模式。 在前一个例子中,任何没有结束的文件名 `.js` 自动获得 `settings.js` 设置为 `false`。 。 。 .

您也可以指定一个 `ignores` 键将迫使匹配这些模式的文件不包含。 如果 `ignores` 键在配置对象中,没有其他键,那么这些被忽略的会永远被应用;否则,这些被忽略的会起到排除的作用。 举个例子:

```js
export default [
    // Always ignored
    {
        ignores: ["**/.git/**", "**/node_modules/**"],
    },

    // .eslintrc.js file is ignored only when .js file matches
    {
        files: ["**/*.js"],
        ignores: [".eslintrc.js"],
        handler: jsHandler,
    },
];
```

您可以在 `ignores` 排除已被忽略的文件,例如:

```js
export default [
    // Ignore all JSON files except tsconfig.json
    {
        files: ["**/*"],
        ignores: ["**/*.json", "!tsconfig.json"],
    },
];
```

### 配置函数

配置数组也可以包括配置函数,当 `extraConfigTypes` 包含 `"function"`。一个配置函数接受单个参数, `context` (由您定义),并且必须返回一个配置对象或一个配置阵列(它不能返回另一个函数). 配置功能允许最终用户在创建适当的配置对象时执行代码. 举个例子:

```js
export default [
    // JS config
    {
        files: ["**/*.js"],
        handler: jsHandler,
    },

    // JSON configs
    function (context) {
        return [
            // match all JSON files
            {
                name: context.name + " JSON Handler",
                files: ["**/*.json"],
                handler: jsonHandler,
            },

            // match only package.json
            {
                name: context.name + " package.json Handler",
                files: ["package.json"],
                handler: packageJsonHandler,
            },
        ];
    },
];
```

当一个配置数组正常化时,每个函数都会被执行,并在配置数组中被替换为返回值.

**说明:** 配置函数也可以是async.

### 配置阵列规范化

一旦一个配置阵列被创建并装入了所有原始配置数据后,它就必须被正常化后才能被使用. 正常化进程贯穿并平整了配置阵列,以及执行所有配置功能以获得其最终值.

要将配置数组正常化,请调用 `normalize()` 上下文对象中的方法和通过:

```js
await configs.normalize({
    name: "MyApp",
});
```

这个 `normalize()` 方法返回一个承诺,所以一定要使用 `await` 操作员。 配置数组实例在位置上正常化,所以不需要创建新的变量.

如果您想要拒绝 async 配置函数, 您可以调用 `normalizeSync()` 换句话说 这种方法是完全同步的,不需要使用 `await` 操作者,因为它不还原诺言:

```js
configs.normalizeSync({
    name: "MyApp",
});
```

**重要内容:** 一次a `ConfigArray` 它已经正常化,不能再进一步改变。 不过,你可以创建一个新的 `ConfigArray` 并在正态实例中通过以创建非正态副本.

### 获取文件配置

要获取文件的配置, 请使用 `getConfig()` 在普通配置阵列上的方法,并在文件名中通过,以获得以下配置:

```js
// pass in filename
const fileConfig = configs.getConfig(
    path.resolve(process.cwd(), "package.json"),
);
```

配置阵列总是返回一个对象, 即使没有匹配给定文件名的配置 。 然后可以检查返回的配置对象,以确定如何进行.

有些事情要记住:

-   如果一个文件名不是绝对路径,则会相对于基础路径目录来解决.
-   返回的配置对象从未有过 `files`, (中文(简体) ), `ignores`, (中文(简体) ), `basePath`,或 `name` 属性;对象上唯一的属性将是指定的其他配置选项.
-   配置数组缓存配置,所以后续调用到 `getConfig()` 同一文件名将快速查找而不是进行其他计算.
-   只有文件名符合条目时才会生成配置 `files` 键。 不匹配配置将无法生成配置 `files` 密钥(配置不包含 `files` 键仅在另一个配置与 a 时应用 `files` 键被应用;没有配置 `files` 从未单独申请)。 任意配置 `files` 键入为 `*` 或结束于 `/**` 或者说 `/*` 将仅在同一条目中的另一条目中应用 `files` 密钥匹配或其他配置匹配.

## 确定被忽略的路径

您可以使用 `isFileIgnored()` 方法和在任何文件的路径中传递,例如此示例:

```js
const ignored = configs.isFileIgnored("/foo/bar/baz.txt");
```

如果以下任何文件属实,则视为忽略 :

-   **其父目录被忽略 .** 例如,如果 `foo` 进入 `ignores`,则 `foo/a.js` 被视为被忽略.
-   **它有一个被忽略的祖先目录.** 例如,如果 `foo` 进入 `ignores`,则 `foo/baz/a.js` 被视为被忽略.
-   **它符合被忽略的文件模式 .** 例如,如果 `**/a.js` 进入 `ignores`,则 `foo/a.js` 财务报告和审定财务报表 `foo/baz/a.js` 被视为被忽略.
-   **如果匹配条目 `files` 和在 `ignores`。 。 。 .** 例如,如果 `**/*.js` 进入 `files` 财务报告和审定财务报表 `**/a.js` 进入 `ignores`,则 `foo/a.js` 财务报告和审定财务报表 `foo/baz/a.js` 被视为被忽略.
-   **文件在外边 `basePath`。 。 。 .** 如果 `basePath` 实值 `/usr/me`,则 `/foo/a.js` 被视为被忽略.

对于目录,请使用 `isDirectoryIgnored()` 在任何目录的路径中,如此示例中:

```js
const ignored = configs.isDirectoryIgnored("/foo/bar/");
```

如果下列任何一种情况属实,则被视为被忽略:

-   **其父目录被忽略 .** 例如,如果 `foo` 进入 `ignores`,则 `foo/baz` 被视为被忽略.
-   **它有一个被忽略的祖先目录.** 例如,如果 `foo` 进入 `ignores`,则 `foo/bar/baz/a.js` 被视为被忽略.
-   **它符合被忽略的文件模式 .** 例如,如果 `**/a.js` 进入 `ignores`,则 `foo/a.js` 财务报告和审定财务报表 `foo/baz/a.js` 被视为被忽略.
-   **如果匹配条目 `files` 和在 `ignores`。 。 。 .** 例如,如果 `**/*.js` 进入 `files` 财务报告和审定财务报表 `**/a.js` 进入 `ignores`,则 `foo/a.js` 财务报告和审定财务报表 `foo/baz/a.js` 被视为被忽略.
-   **文件在外边 `basePath`。 。 。 .** 如果 `basePath` 实值 `/usr/me`,则 `/foo/a.js` 被视为被忽略.

**重要内容:** 类似模式 `foo/**` 意思是说 `foo` 财务报告和审定财务报表 `foo/` 为: _没有_ 忽略时 `foo/bar` 被忽略。 如果你想忽略的话 `foo` 及其所有子目录,使用图案 `foo` 或者说 `foo/` 内 `ignores`。 。 。 .

## 缓存机制

每个 `ConfigArray` 积极缓存配置对象以避免不必要的工作. 这种缓存有两种方式:

1.  **以文件为基础的 Caching.** 对于被传递到方法的每个文件名,产生的配置都会被缓存到文件名上,这样你总是被保证从中获取相同的对象 `getConfig()` 当你通过相同的文件名时.
2.  **以索引为主的 Caching.** 当计算出一个配置时,用于创建配置的配置元素也会被缓存. 因此,如果给定的文件名匹配元素 1、 5 和 7, 由此产生的配置将缓存 : `1,5,7`。这样,如果通过另一个匹配相同配置元素的文件,结果已经知道,无需重新计算。 这意味着两个匹配所有相同元素的文件将返回相同的配置 `getConfig()`。 。 。 .

## 鸣谢

这个项目的设计受到关于ESLint RFC的反馈的影响,并吸收了以下观点:

-   泰迪·卡茨 (@not-an-aardvark) (英语)
-   长岛同仁(@mysticata)
-   凯·卡特多(@kaicataldo)

## 许可证

Apache 2.0 (英语)

## 发起人

以下公司,组织,个人支持ESLint的持续维护与发展. [成为发起人](https://eslint.org/donate) 让你的标志在我们的读取器和 [网站](https://eslint.org/sponsors)。 。 。 .

### 白金赞助商

[![Automattic](https://images.opencollective.com/automattic/d0ef3e1/logo.png)](https://automattic.com/)

### 黄金赞助商

[![Qlty Software](https://images.opencollective.com/qltysh/33d157d/logo.png)](https://qlty.sh/)

### 白银赞助商

[![Vite](https://images.opencollective.com/vite/d472863/logo.png)](https://vite.dev/) [![Liftoff](https://images.opencollective.com/liftoff/2d6c3b6/logo.png)](https://liftoff.io/) [![StackBlitz](https://avatars.githubusercontent.com/u/28635252)](https://stackblitz.com/)

### 青铜赞助商

[![Cybozu](https://images.opencollective.com/cybozu/933e46d/logo.png)](https://cybozu.co.jp/) [![SAP](https://avatars.githubusercontent.com/u/2531208)](https://opensource.sap.com/) [![CrawlJobs](https://images.opencollective.com/crawljobs-poland/fa43a17/logo.png)](https://www.crawljobs.com/) [![aeriusventilation's Org](https://images.opencollective.com/aeriusventilations-org/avatar.png)](https://npmcn.com/package/%40eslint/config-array/#) [![Depot](https://images.opencollective.com/depot/39125a1/logo.png)](https://depot.dev/) [![Icons8](https://images.opencollective.com/icons8/7fa1641/logo.png)](https://icons8.com/) [![Discord](https://images.opencollective.com/discordapp/f9645d9/logo.png)](https://discord.com/) [![GitBook](https://avatars.githubusercontent.com/u/7111340)](https://www.gitbook.com/) [![HeroCoders](https://avatars.githubusercontent.com/u/37549774)](https://herocoders.com/) [![TestMu AI Open Source Office (Formerly LambdaTest)](https://avatars.githubusercontent.com/u/171592363)](https://www.lambdatest.com/)

### 技术赞助商

技术赞助者允许我们免费利用其产品和服务,作为对开放源生态系统和我们工作的贡献的一部分.

[![Netlify](https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/netlify-icon.svg)](https://netlify.com/) [![Algolia](https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/algolia-icon.svg)](https://algolia.com/) [![1Password](https://raw.githubusercontent.com/eslint/eslint.org/main/src/assets/images/techsponsors/1password-icon.svg)](https://1password.com/)

## 常见问题

### @eslint/config-array 是什么？

通用 glob 配置匹配 \.

### 如何安装 @eslint/config-array？

在项目目录运行 npm install @eslint/config-array，或使用 pnpm add / yarn add / bun add。

### @eslint/config-array 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @eslint/config-array 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @eslint/config-array 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.19\.0 \|\| ^22\.13\.0 \|\| \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @eslint/config-array 可以商用吗？

@eslint/config-array 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @eslint/config-array 的下载量有多少？

根据 npm 官方下载统计，@eslint/config-array 在 2026/10/07 – 2026/11/05 这 30 天内被下载 517,948,465 次，日均约 17,264,949 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @eslint/config-array 还在维护吗？

最新版本 0\.23\.5 发布于 2026/04/08（6 个月前）；至今共发布 20 个版本，其中过去 12 个月发布了 8 个；首次发布于 2024/05/31。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。