@wordpress/eslint-plugin

ESLint 插件，包含用于 WordPress 开发的配置和自定义规则。

安装

安装模块

npm install @wordpress/eslint-plugin --save-dev

注意：此软件包需要具有长期支持状态的 Node.js 版本（请参阅Active LTS 或 Maintenance LTS 版本）。它与旧版本不兼容。

用法

最低 ESLint 版本： ^9.0.0 || ^10.0.0

从旧版本升级？ 请参阅 ESLint v10 迁移指南，以获取有关重大更改、迁移步骤和故障排除的全面指南。

Flat config（ESLint v9+，推荐）

在项目根目录中创建一个 eslint.config.mjs 文件：

import wordpress from '@wordpress/eslint-plugin';

export default [ ...wordpress.configs.recommended ];

你可以在展开操作符之后添加自己的覆盖配置：

import wordpress from '@wordpress/eslint-plugin';

export default [
    ...wordpress.configs.recommended,
    {
        rules: {
            // your custom rule overrides
        },
    },
];

有关更多信息，请参阅 ESLint flat config 文档。

Legacy eslintrc（仅限 ESLint v9，已弃用）

如果你仍在使用带有传统 .eslintrc.* 格式的 ESLint v9，则提供了一个兼容性包装器：

// .eslintrc.js
const wordpress = require( '@wordpress/eslint-plugin/eslintrc' );

module.exports = wordpress.configs.recommended;

所有配置预设都可以通过包装器访问（例如，wordpress.configs.esnext、wordpress.configs[ 'recommended-with-formatting' ]）。

注意： eslintrc 包装器已被弃用，并将在下一个主要版本中移除。ESLint v10 完全不支持 .eslintrc.* 文件。请迁移到 flat config。

关于 recommended 预设

recommended 预设将包括管理 ES2015+ 环境的规则，并包含来自 eslint-plugin-jsdoc、eslint-plugin-jsx-a11y、eslint-plugin-react 和其他类似插件的规则。

此预设提供了与 eslint-plugin-prettier 软件包的可选集成，该集成运行 Prettier 代码格式化程序并将差异报告为单独的 ESLint 问题。你可以通过单独安装 prettier 软件包来激活它：

npm install prettier --save-dev

最后，此规则集还包含与 @typescript-eslint/eslint-plugin 软件包的可选集成，使 ESLint 能够支持 TypeScript 语言。你可以通过单独安装 typescript 软件包来激活它：

npm install typescript --save-dev

还有一个 recommended-with-formatting 规则集，适用于希望确保从不激活 Prettier 和 TypeScript 集成的项目。此预设启用了原生的 ESLint 代码格式化规则。

规则集

或者，你可以选择仅使用插件提供的更细粒度的规则集。这些包括：

• custom – 用于 WordPress 开发的自定义规则。
• es5 – 用于传统 ES5 环境的规则。
• esnext – 用于 ES2015+ 环境的规则。
• i18n – 用于国际化的规则。
• jsdoc – 用于 JSDoc 注释的规则。
• jsx-a11y – 用于 JSX 可访问性的规则。
• react – 用于 React 组件的规则。
• test-e2e – 用于使用 Puppeteer 编写的端到端测试的规则。
• test-unit – Vitest 测试的推荐规则，使用显式导入，允许通过变量传递标题。这从 Jest 27.0.0 主要版本边界处发生变化。Jest 使用者可以直接配置 eslint-plugin-jest。请参阅 迁移指南。
• test-playwright – 用于使用 Playwright 编写的端到端测试的规则。

例如，如果你的项目不使用 React，则可以仅使用 ESNext 规则：

// eslint.config.mjs
import wordpress from '@wordpress/eslint-plugin';

export default [ ...wordpress.configs.esnext ];

这些规则可以累积使用，因此你可以同时展开 esnext 和 custom 规则集，但省略 react 和 jsx-a11y 配置。

细粒度规则集不会定义任何环境全局变量。因此，如果它们对你的项目是必需的，你需要自行定义它们。

规则

从 eslintrc 迁移到 flat config

如果您正在从使用 .eslintrc.* 文件的先前版本升级：

1. 用 eslint.config.mjs 文件替换您的 .eslintrc.* 文件。
2. 将 extends 数组更改为 import + spread：

   // Old (.eslintrc.js)
   module.exports = {
       extends: [ 'plugin:@wordpress/eslint-plugin/recommended' ],
   };
   
   // New (eslint.config.mjs)
   import wordpress from '@wordpress/eslint-plugin';
   export default [ ...wordpress.configs.recommended ];
   

3. 将 overrides 转换为带有 files 模式的单独配置对象。
4. 使用 globals 包将 env 替换为 languageOptions.globals。
5. 删除您的 .eslintignore 文件并将模式移至 ignores 配置对象中。

6. 更新内联注释中的规则前缀：eslint-comments/* 已重命名为 @eslint-community/eslint-comments/*。例如：

   - /* eslint-disable eslint-comments/no-unlimited-disable */
   + /* eslint-disable @eslint-community/eslint-comments/no-unlimited-disable */
   

7. 移除所有 /* eslint-env */ 注释 — 它们在 ESLint v10 中不再受支持。请在配置中使用 languageOptions.globals。

有关包含示例和故障排除的全面指南，请参阅 Gutenberg ESLint v10 迁移指南。有关通用 flat config 详细信息，还请参阅 ESLint 迁移指南。

为此包做出贡献

这是 Gutenberg 项目的一部分独立包。该项目组织为一个 monorepo。它由多个自包含的软件包组成，每个包都有特定的用途。此 monorepo 中的包发布到 npm，并被 WordPress 以及其他软件项目使用。

要了解有关为此包或整个 Gutenberg 做出贡献的更多信息，请阅读项目的主 贡献者指南。