# @automattic/eslint-plugin-wpvip 中文文档

规范地址：https://npmcn.com/package/%40automattic/eslint-plugin-wpvip/

版本：2\.0\.1
npm 元数据更新时间：2026-10-05T16:36:31.398Z
中文译文更新时间：2026-11-07T06:54:59.461Z
软件包许可：GPL-2\.0\+

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

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

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

- 包体积（解压后）：82.5 kB，35 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：^22\.22\.2 \|\| \>=24\.15\.0
- 运行依赖：19 个
- peer 依赖：jest ^29\.0\.0 \|\| ^30\.0\.0，react ^18\.0\.0 \|\| ^19\.0\.0，eslint ^9\.39\.1 \|\| ^10\.0\.0，prettier ^3\.0\.0，typescript ^5\.0\.0 \|\| ^6\.0\.0
- 首次发布：2022-04-29T16:24:18.663Z
- 最新版本发布：2026-10-05T16:36:30.982Z
- 近 30 天下载量：10858（2026-10-07 至 2026-11-05，npm 官方下载统计）
- 已发布版本数：47（近 12 个月 9 个）

## 中文简介

内部 WordPress VIP 项目的 ESLint 插件

## 安装

```sh
npm install @automattic/eslint-plugin-wpvip
```

也可以使用：`pnpm add @automattic/eslint-plugin-wpvip`、`yarn add @automattic/eslint-plugin-wpvip`、`bun add @automattic/eslint-plugin-wpvip`

## README

# WordPress VIP ESLint 插件

这是提供WordPressVIP(内部)JavaScript和TypeScript编码标准的ESLint插件. 它的灵感和借自 [`@wordpress/eslint-plugin`](https://github.com/WordPress/gutenberg/tree/trunk/packages/eslint-plugin)。 。 。 .

## 安装

安装 `eslint` 财务报告和审定财务报表 `@automattic/eslint-plugin-wpvip` 你的项目.

```sh
npm install --save-dev eslint @automattic/eslint-plugin-wpvip
```

ESLint 9 (英语)`^9.39.1`)和ESLint 10支持.

当您的工程也安装时, 可选集成会自动检测 `typescript`, (中文(简体) ), `jest`, (中文(简体) ), `react`,或 `prettier`。这些软件包被宣布为可选的对等依赖,这样消费者就可以选择进入他们实际使用的堆栈.

### ESLint 10 (英语)

`eslint-plugin-jsx-a11y` 财务报告和审定财务报表 `eslint-plugin-react` 与 ESLint 10 合作( 此插件 shims) `eslint-plugin-react` 与 [`@eslint/compat`](https://www.npmjs.com/package/@eslint/compat))),但他们还没有发布宣布ESLint 10在同行依赖性中的发布. 为了避免 `ERESOLVE` npm 出错, 请在您的工程中添加这些覆盖 `package.json`。 。 。 . `$eslint` 指您的项目本身 `eslint` 输入,所以 `eslint` 必须直接在 `devDependencies` (或 `dependencies`:

```json
"overrides": {
    "eslint-plugin-jsx-a11y": { "eslint": "$eslint" },
    "eslint-plugin-react": { "eslint": "$eslint" }
}
```

### 升级到 2. 0

2.0 添加 ESLint 10 支持并包含这些断开更改 :

-   **`eslint-plugin-import` 改为: [`eslint-plugin-import-x`](https://github.com/un-ts/eslint-plugin-import-x)。 。 。 .** 登记在 `import` 命名空间, 因此规则 ID 如 `import/order` 财务报告和审定财务报表 `eslint-disable` 评论意见不变。 不过:
    -   设置现在使用 `import-x/` 前缀. `import/*` 设置( e)`import/resolver`, (中文(简体) ), `import/internal-regex`, (中文(简体) ), `import/core-modules`,)被忽略;例如重命名它们. `import/resolver` → `import-x/resolver`。 。 。 .
    -   不注册 `eslint-plugin-import` 下级 `import` 自己; ESLint 会扔 `Cannot redefine plugin "import"`。 。 。 .
    -   `import/enforce-node-protocol-usage` 不存在于 `eslint-plugin-import-x`; 从您的配置中删除 .
    -   `eslint-plugin-import` 不再安装此软件包。 如果你的配置需要它, 添加到自己的 `devDependencies`。 。 。 .
-   **JavaScript 文件用 ESLint 的默认解析器( espree) 解析** 改为 `@babel/eslint-parser`。您的项目中的 Babel 配置已不再应用,因此,只有 Babel 理解的语法(例如流或遗留的装饰)不支持 `parserOptions.babelOptions` 编号 : `requireConfigFile` 被忽略。 ECMAScript版本遵循了ESLint的默认(`latest`),因此是新的内置全球(例如. `SuppressedError`, (中文(简体) ), `Iterator`) 被确认.
-   **已折旧的核心格式规则已移入 [`@stylistic/eslint-plugin`](https://eslint.style/)。 。 。 .** ESLint正在删除其格式规则,所以 `formatting`, (中文(简体) ), `javascript` 财务报告和审定财务报表 `react` 现在使用的配置 `@stylistic/*` 配置相同选项的规则(例如:. `indent` → `@stylistic/indent`, (中文(简体) ), `func-call-spacing` → `@stylistic/function-call-spacing`) (中文(简体) ). 重命名任何覆盖或 `eslint-disable` 对这些规则的评论;凌驾于旧的核心名称之上不再有任何效果. `no-new-symbol` 改为: `no-new-native-nonconstructor`。 。 。 .
    -   结果并不总是相同的: `@stylistic` 在被冻结的核心规则中修正错误。 值得注意的是, `@stylistic/indent` 现在检查其缩进混合标签和空格的行( 核心) `indent` 跳过他们,比如结束 `}` 编号 : `)` 编号 : `]` 缩入标签外加两个空格,缩入链式任务(`a = b = c`不一样 只有格式化规则有效,即不使用 `prettier` 装潢,这关了他们.
    -   此软件包登记册 `@stylistic/eslint-plugin` 下级 `@stylistic`。如果您的配置同时注册,请确保 npm 解决同一副本(兼容的版本范围),否则 ESLint 将丢弃 `Cannot redefine plugin "@stylistic"`。 。 。 .
-   **这个 `jsdoc` 配置** 不再启用 `jsdoc/newline-after-description`,从中移除 `eslint-plugin-jsdoc` 使配置无法装入.
-   **ESLint 语录 `^9.39.1` 或者说 `^10.0.0` 需要时间** (先前为 `^9.7.0`) (中文(简体) ).
-   **节点.js `^22.22.2 || >=24.15.0` 需要时间**,包括使用ESLint 9(Node.js 20是报废). `eslint-plugin-jsdoc` 65 要求这些版本; `@stylistic/eslint-plugin` 仅限无害环境管理,并装入 `require()`,这需要节点的内置 `require(esm)` 支助,和 `@eslint/compat` (用于支持) `eslint-plugin-react` eSLint 10)需要节点.js 20.19+/ 22.13+.

## 捐款

见 [捐款额](https://github.com/Automattic/eslint-config-wpvip/blob/trunk/CONTRIBUTING.md) 关于开发、测试、出版等的详细情况.

## 配置

创建一个 `eslint.config.cjs` 文档。 这个 `.cjs` 扩展让节点js把它当作普通JS,即使您 `package.json` 已经 `"type": "module"`。本 README 中的例子使用此文件 :

```js
const wpvip = require( '@automattic/eslint-plugin-wpvip' );

module.exports = [ ...wpvip.configs.recommended ];
```

就这样! 它与大多数JavaScript和TypeScript项目自动工作.

这个 `typescript`, (中文(简体) ), `testing`, (中文(简体) ), `react`,以及 `prettier` 页:1 `recommended` 仅在安装相应的软件包时才加载。 如果你需要那些可选的配置 解决在前面而不是何时 `recommended` 已装入,需要 `init` 先说 它使用相同的检测 `recommended`,所以其软件包未安装的可选集仍然被跳过:

```js
require( '@automattic/eslint-plugin-wpvip/init' );
```

配置用于与ESLint合作的代码编辑器会自动取出规则并标出任何错误或警告.

如果您的工程只使用 JavaScript, 您不需要安装可选的对等器 。 如果使用模块 `typescript`, (中文(简体) ), `testing`, (中文(简体) ), `react`,或 `prettier` 直接配置,首先在工程中安装相应的软件包.

要跳过文件或路径,请添加配置对象 `ignores` (例如 `{ ignores: [ 'dist/**' ] }`)到数组.

软件包脚本可以用于自动运行林入和格式化命令. 这里有一些你项目的建议脚本 `package.json`\- 只复制那些对你有用的。 这个 `cmd:` 脚本帮助您不重复动词 CLI 参数来作曲命令.

```json
{
    "scripts": {
        "cmd:format": "prettier '**/*.(js|json|jsx|md|ts|tsx|yml|yaml)'",
        "cmd:lint": "eslint",
        "format": "npm run cmd:format -- --write",
        "format:check": "npm run cmd:format -- --check",
        "lint": "npm run cmd:lint .",
        "lint:fix": "npm run cmd:lint . -- --fix",
        "lint:ignore-warnings": "npm run cmd:lint . -- --quiet"
    }
}
```

**说明:** ESLint 读取忽略图案 `ignores` 键入 `eslint.config.cjs`; 重复使用 `.gitignore`,参见 [`includeIgnoreFile`](https://eslint.org/docs/latest/use/configure/ignore#including-gitignore-files)。Pretier 自动忽略在 `.prettierignore` 或者可以瞄准目标 `.gitignore` 使用 `--ignore-path`。 。 。 .

## 建议配置

"推荐"配置包括JavaScript,TypeScript,Jest,和React的规则,包括与格式化和白色空间有关的规则. 这是要严格! 有观点的默认会让我们的代码库保持一致,并减少我们在项目间进行上下文切换时所经历的摩擦.

当然,这个推荐的配置对于每个项目来说可能并不理想,所以可以自由地使用可用的模块配置来"自建". 建议的配置相当于:

```js
const wpvip = require( '@automattic/eslint-plugin-wpvip' );

module.exports = [
    ...wpvip.configs.javascript,
    ...wpvip.configs.formatting,
    ...wpvip.configs.typescript, // when "typescript" is installed
    ...wpvip.configs.testing, // when "jest" is installed
    ...wpvip.configs.react, // when "react" is installed
    ...wpvip.configs.prettier, // when "prettier" is installed
];
```

注意配置的顺序可能很重要,因为它们可以包含覆盖. 特别重要的是增加: `prettier` 最后一个配置 .

### 高级

安装 [WP 预演](https://github.com/Automattic/wp-prettier) v3.x 从其他格式化规则中受益:

```sh
npm i --save-dev --save-exact "prettier@npm:wp-prettier@3.0.3"
```

此 repo 也提供了 Pretier 配置, 您可以使用以下选项 `.prettierrc`数字 :

```json
"@automattic/eslint-plugin-wpvip/prettierrc"
```

关于最大利益,见 [Pretier 在编辑器中保存启用格式的文件](https://prettier.io/docs/en/editors.html)。这使得您可以在Pretier处理格式化时集中精力进行编码.

### 编辑器配置

[编辑器配置](https://editorconfig.org/) 提供了额外的格式规则,并与Pretier合作良好. 复制 [`.editorconfig` 文件](https://npmcn.com/package/%40automattic/eslint-plugin-wpvip/.editorconfig) 从这回转到你的项目.

## 国 际

这个 `cli` 配置允许某些行为通常与最佳做法相悖,但在生成 CLI 工具的代码库中有用:

```js
module.exports = [ ...wpvip.configs.recommended, ...wpvip.configs.cli ];
```

如果你的项目不是一个CLI工具,但偶尔会孕育出孩子的过程,你可能不需要这个配置. 相反,只有在必要的情况下才禁用这些规则,并包含一个解释:

```js
// Running a fixed, trusted command.
// eslint-disable-next-line security/detect-child-process
const { execSync } = require( 'child_process' );
```

请注意: `console.log` 仍然被禁止([这里请看一个解释](https://github.com/Automattic/eslint-config-wpvip/pull/198#issuecomment-2015322062)) (中文(简体) ). 如果你是写一次性 节点脚本, 您可以禁用每个文件的规则 :

```js
/* eslint-disable no-console */
```

## 联合来文文件

JSDoc被认为是可选的,尤其是与TypeScript和OpenAPI文档等更好的替代品相比. 如果你想强制使用JSDoc,请使用 `jsdoc` 配置 :

```js
module.exports = [ ...wpvip.configs.recommended, ...wpvip.configs.jsdoc ];
```

请注意,规则需要 `@param` 财务报告和审定财务报表 `@return` 类型在 TypeScript 文件中得到放松.

## "弱"的配置

这个插件为正在向更强标准过渡的遗留代码库提供了一些所谓的"弱"配置. 这些配置降级从 `recommended` 配置为警告 。 在代码编辑器和其他输出中仍然可以看到警告,但不会出错的集成工作流程.

这些配置用于临时用途,不应长期使用. 我们也不建议使用如下工具: [连接线](https://github.com/Automattic/eslines) 忽略错误或警告。 虽然意图是防止大规模的改变并缓慢地过渡到更强的标准,但效果通常是过渡会停滞并最终完全停止.

三"弱"相貌可知: `weak-javascript`, (中文(简体) ), `weak-typescript`,以及 `weak-testing`虽然总是欢迎就这一项目提出要求,但请认真考虑是否确实有必要在这些配置中增加规则。 理想的是,我们努力从这些配置中删除规则,直到不再需要它们.

## 常见问题

### @automattic/eslint-plugin-wpvip 是什么？

内部 WordPress VIP 项目的 ESLint 插件

### 如何安装 @automattic/eslint-plugin-wpvip？

在项目目录运行 npm install @automattic/eslint-plugin-wpvip，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：eslint（^9\.39\.1 \|\| ^10\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @automattic/eslint-plugin-wpvip 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/automattic\_\_eslint-plugin-wpvip 是否存在。

### @automattic/eslint-plugin-wpvip 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @automattic/eslint-plugin-wpvip 需要什么版本的 Node\.js？

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

### @automattic/eslint-plugin-wpvip 可以商用吗？

@automattic/eslint-plugin-wpvip 使用 GPL-2\.0\+ 许可。强 Copyleft：分发包含该代码的软件时，整个作品需以兼容的 GPL 许可开源。仅在内部使用、不对外分发时不触发此义务。以上为概括，不构成法律意见，请以许可原文为准。

### @automattic/eslint-plugin-wpvip 的下载量有多少？

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

### @automattic/eslint-plugin-wpvip 还在维护吗？

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