ESLint配置项详解，并将配置打包npm

本文正在参加「」

本文针对 ESLint 8+ 版本

配置文件格式

ESLint 配置文件可以使用多种文件格式，常用的有以下几种：

• .eslintrc.js：使用 JavaScript 编写的配置文件，返回一个配置对象。
• .eslintrc.yaml、.eslintrc.yml：使用 YAML 语言编写的配置文件。
• .eslintrc.json：使用 JSON 格式编写的配置文件。
• .eslintrc.cjs：使用这种配置时，中需要在package.json中配置type":"module"。
• eslintConfig：使用npm包进行配置。
• .eslintrc：普通配置文件

此外还有行内配置：

• /* eslint-disable */ 和 /* eslint-enable */，禁用启用规则
• /* global */，定义全局变量
• /* eslint */，配置规则
• /* eslint-env */，指定当前运行环境

现在，有一种新的配置文件类型：eslint.config.js，官方将在 v9 版本全面使用该配置类型。

其中，推荐使用 .js 文件格式，因为它可以使用 JavaScript 的所有特性，方便编写复杂的配置规则。本文以推荐的格式为例来讲解配置:

// .eslintrc.js
module.exports = {
...
}

//eslint.config.js
export default [

]

常用配置项

root

指定ESLint在查找配置文件时的起始位置。

假设现在目录层级如下：

project/
├── package.json
├── .eslintrc.js
├── src/
│   ├── .eslintrc.js
│   └── index.js
└── test/
    ├── .eslintrc.js
    └── test.js

我们在 顶层.eslintrc.js 中配置 root：

// project/.eslintrc.js
module.exports = {
  root: true,
  // ...
}

这告诉了ESLint应该使用此文件作为起始位置来查找其他配置文件。这将确保ESLint始终使用project/.eslintrc.js作为项目中所有文件的配置文件，而不是使用子目录中的其他配置文件。

如果在上述的例子中没有指定"root"字段，ESLint会使用最近的配置文件来检测代码，如果当前目录下没有配置文件，ESLint会继续向上查找父目录，直到找到一个配置文件为止。

env

用来指定校验环境。它告诉 ESLint 代码运行在哪个环境中，从而帮助 ESLint 更好地理解您的代码并检测潜在的问题。

配置如下：

env: {
  es6: true /** 启用除了modules以外的所有 ES6 特性,开启后会自动设置ecmaVersion为6 */,
  node: true /** Node.js 全局变量和 Node.js 作用域 */,
  browser: true /** 浏览器全局变量 */,
  commonjs: true /**  CommonJS 全局变量和 CommonJS 作用域 (用于 Browserify/WebPack 打包的只在浏览器中运行的代码) */,
  jest: false /** Jest 全局变量 */,
  jquery: false /** jQuery 全局变量 */,
  'shared-node-browser': false /** Node.js 和 Browser 通用全局变量 */,
  worker: false /** Web Workers 全局变量 */,
  amd: false /** 将 require() 和 define() 定义为像 amd 一样的全局变量 */,
  mocha: false /** 添加所有的 Mocha 测试全局变量 */,
  jasmine: false /** 添加所有的 Jasmine 版本 1.3 和 2.0 的测试全局变量。 */,
  phantomjs: false /** phantomjs 全局变量 */,
  protractor: false /** protractor 全局变量 */,
  qunit: false /** QUnit 全局变量 */,
  prototypejs: false /** Prototype.js 全局变量 */,
  shelljs: false /** ShellJS 全局变量 */,
  meteor: false /** Meteor 全局变量 */,
  mongo: false /** MongoDB 全局变量 */,
  applescript: false /** AppleScript 全局变量 */,
  nashorn: false /** Java 8 Nashorn 全局变量 */,
  serviceworker: false /** Service Worker 全局变量 */,
  atomtest: false /** Atom 测试全局变量 */,
  embertest: false /** Ember 测试全局变量 */,
  webextensions: false /** WebExtensions 全局变量 */,
  greasemonkey: false /** GreaseMonkey 全局变量 */,
}

parser

指定用于解析JavaScript代码的解析器。ESLint默认使用 esprima 解析器，但是可以通过"parser"配置来使用其他解析器。

常用的解析器如下：

1. esprima：默认的解析器，用于解析ECMAScript 5到ECMAScript 2021之间的JavaScript代码。
2. @babel/eslint-parser：由Babel项目提供的解析器，用于解析ES6+代码。
3. @typescript-eslint/parser：由TypeScript团队提供的解析器，用于解析TypeScript代码。
4. eslint-plugin-html：用于解析HTML文件中的JavaScript代码。
5. vue-eslint-parser：用于解析Vue单文件组件中的JavaScript代码。

parserOptions

给配置的解析器添加可选配置项。

如果使用的是默认parser配置，可以有如下配置：

// .eslintrc.js
module.exports = {
  parser: "esprima",
  parserOptions: {
    ecmaVersion: 2022, 
    sourceType: "module",
    range: true,
    loc: true,
  },
  // ...
}

字段解析：

• ecmaVersion: 指定要解析的 ECMAScript 版本。可以设置为数字（如 3、5、6、7、8、9、10、11、12、13、2020、2021 等）或字符串（如 "latest"）。默认为 5。
• sourceType: 指定要解析的模块系统类型。可选值为 "script"（默认）或 "module"。
• ecmaFeatures: 一个对象，用于启用或禁用 ECMAScript 中的特定语言功能。可用的选项包括：
  • globalReturn：允许在全局作用域中使用 return 语句。
  • impliedStrict：允许在非严格模式下解析为严格模式。
  • jsx：启用 JSX 语法。
  • experimentalObjectRestSpread：启用对象的 rest 和 spread 操作符。
• allowImportExportEverywhere: 允许在代码的任何位置使用 import 和 export 语句。默认为 false。
• codeFrame: 当发生语法错误时，提供更详细的错误信息。默认为 true。
• requireConfigFile: 如果设置为 true，则必须提供 tsconfig.json 或 .eslintrc.* 文件来配置解析器。默认为 false。
• babelOptions: 传递给 @babel/parser 的选项对象。示例如下：

babelOptions: {
  ecmaVersion: "es2020",
  ecmaFeatures: {
    globalReturn: true,
    jsx: true,
  },
  lib: ["ES2020"],
},

• tsconfigRootDir: 指定 TypeScript 配置文件的根目录。默认为解析 tsconfig.json 文件的目录。

如果使用@babel/eslint-parser解析器，则可以有如下配置：

// .eslintrc.js
module.exports = {
  parser: "@babel/eslint-parser",
  parserOptions: {
    ecmaVersion: 2022,
    sourceType: "module",
    ecmaFeatures: {
      jsx: true,  //支持 jsx
    },
  },
  // ...
}

若使用 @typescript-eslint/parser，可以使用如下配置：

// .eslintrc.js
module.exports = {
  parser: "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": 2021,
    "sourceType": "module",
    "project": "./tsconfig.json",
    "tsconfigRootDir": "./",
    "extraFileExtensions": [".tsm"]
  },
}

globals

指定全局变量的一个配置项。在 JavaScript 中，如果一个变量没有经过声明就被使用，会导致该变量被当作全局变量处理，这可能会导致一些潜在的问题。通过配置 globals，我们可以告诉 ESLint 这些变量是全局变量，从而避免出现这种问题。

globals 可以是一个对象，键为全局变量的名称，值为该变量的使用情况，可以是 readonly、writable 或 off。例如：

{
  "globals": {
    "foo": "writable",
    "bar": "readonly",
    "baz": "off"
  }
}

在上面的示例中，foo 和 bar 都被指定为全局变量，foo 可以被写入，而 bar 是只读的，baz 被关闭，也就是说，ESLint 不会对它进行任何检查。

可以将 globals 视为一个白名单，其中包含了明确指定的全局变量，而其他未被列出的变量会被认为是未定义的，从而避免了不经意地使用未声明的变量而导致的错误。

需要注意的是，使用全局变量可能会降低代码的可读性和可维护性，因此应该谨慎使用，并且只在确实需要使用全局变量时才使用。同时，globals 可能也会导致一些不可预测的问题，因此建议仅在必要时使用。

rules

配置文件中最常用的配置项之一，用于设置 ESLint 的规则和规则的错误等级。rules 配置项是一个对象，它的每个属性表示一个规则，属性值表示该规则的错误等级。

配置方式：

"rules": {
    "eqeqeq": "off",  // 关闭告警
    "no-undef": "warn", // 警告级别
    "react/prop-types": "error", // 错误级别
}

配置项还有第二个参数：

"semi": ["error", "always"] // 要求在语句末尾始终使用分号。
"semi": ["error", "never"] // 要求在语句末尾不使用分号。

当然了，也可以这样写来拦截特定的文件：

overrides: [
  {
    files: ["*.ts", "*.tsx"],
    rules: {
      "no-undef": "off",
      "react/prop-types": "off",
      "semi": "off"
    },
  },
],

要注意规则集之间的顺序问题，后面的规则集会覆盖前面的规则集。如果需要保留前面的规则集中的规则：

"rules": Object.assign({}, require("eslint-config-airbnb/rules"))

常见的rule有如下这些，

• no-var: 禁止使用 var 关键字声明变量，使用 let 或 const 代替。
• no-unused-vars: 禁止声明变量但未使用，减少代码冗余。
• no-console: 禁止使用 console 语句，避免代码在生产环境中泄漏敏感信息。
• semi: 要求在语句末尾使用分号，规范代码风格。
• indent: 要求使用指定的缩进风格，提高代码可读性。
• quotes: 要求在字符串周围使用指定的引号类型，规范代码风格。
• no-undef: 禁止使用未声明的变量，减少错误出现的概率。
• no-extra-parens: 禁止出现不必要的括号，提高代码可读性。
• no-multiple-empty-lines: 禁止出现多行空白行，提高代码可读性。
• no-trailing-spaces: 禁止行末出现空格，提高代码可读性。
• no-unreachable: 禁止出现无法到达的代码，减少代码冗余。
• no-useless-return: 禁止出现不必要的 return 语句，减少代码冗余。

React

• react/jsx-uses-react: 检测是否使用了 React 库，如果没有使用则报错。
• react/jsx-uses-vars: 检测是否声明了 JSX 变量，如果声明了但未使用则报错。
• react/jsx-no-undef: 检测是否使用了未定义的 JSX 变量，如果使用了则报错。
• react/jsx-indent: 要求 JSX 元素的缩进为指定数量的空格。
• react/jsx-indent-props: 要求 JSX 属性的缩进为指定数量的空格。
• react/no-unescaped-entities: 禁止在 JSX 中使用未转义的 HTML 实体字符。
• react/prop-types: 检测是否为组件声明了 props 类型定义，如果没有则报错。

Vue

• vue/html-indent: 要求模板中的缩进为指定数量的空格。
• vue/no-unused-components: 检测是否注册了但未使用的组件，如果有则报错。
• vue/no-unused-vars: 检测是否声明了但未使用的变量，如果有则报错。
• vue/require-prop-types: 要求组件声明 props 类型定义。
• vue/require-default-prop: 要求组件声明 props 的默认值。
• vue/require-v-for-key: 要求使用 v-for 指令时为每个项提供唯一的 key 属性。

等等..

除此之外，不同的插件还有对应的rule，可查看对应文档来配置。

plugins

用来指定插件的一个选项。插件是一种扩展 ESLint 功能的方式，可以用于检查特定类型的问题或者应用特定的编码规范。ESLint 插件通常是一个 npm 包，包含一组规则和相关的配置，通过 plugins 选项将其引入到项目中，就可以使用这些规则来检查代码了。

ESLint 插件通常需要配合对应的规则进行使用，可以通过 extends 选项来继承插件的规则。常用的插件如下：

1. eslint-plugin-import：用于检查模块导入的规范性，包括路径、文件类型和文件内容等方面的检查。
2. eslint-plugin-react：用于检查 React 代码的规范性，包括 JSX 语法、组件使用和生命周期等方面的检查。
3. eslint-plugin-vue：用于检查 Vue.js 代码的规范性，包括模板、组件和指令等方面的检查。
4. eslint-plugin-jest：用于检查 Jest 测试代码的规范性，包括测试名称、匹配器和断言等方面的检查。
5. eslint-plugin-node：用于检查 Node.js 代码的规范性，包括 API 使用、文件系统和子进程等方面的检查。
6. eslint-plugin-prettier：用于将 Prettier 代码格式化集成到 ESLint 中，可以通过配置来自动修复代码格式问题。
7. eslint-plugin-security：用于检查代码中的安全问题，包括跨站点脚本攻击、命令注入和 SQL 注入等方面的检查。

等等...

这里以 eslint-plugin-react 为例讲解配置：

安装：

npm install eslint-plugin-react --save-dev

使用：

{
  "plugins": ["react"],
  "extends": ["eslint:recommended", "plugin:react/recommended"],
  "rules": {
    "react/jsx-props-no-spreading": "off",
    "react/jsx-props-no-spreading": [
      "error",
      {
        "exceptions": ["Component"],
        "html": "enforce",
        "custom": "ignore"
      }
    ]
  }
}

在上面的配置中，使用了 eslint:recommended 和 plugin:react/recommended 扩展，分别表示使用了 ESLint 推荐的规则和 eslint-plugin-react 的推荐规则。这些规则可以通过 rules 配置项进行修改和覆盖。

extends

用来继承和扩展 ESLint 规则集的配置项。通过 extends，可以将现有的规则集合并到自己的规则配置中，也可以基于现有的规则集进行扩展和定制化。其与 plugins的区别是，前者集成了后者的功能，而且自带了配置规则rules。

ESLint 提供了多个内置规则集，包括 eslint:recommended、plugin:@typescript-eslint/recommended、plugin:react/recommended、plugin:vue/recommended 等。通过在配置文件中设置 extends 为内置规则集的名称，可以直接使用内置规则集中的规则。

除了内置规则集外，还有许多第三方规则集可以使用，比如 airbnb、standard、prettier 等。

如果需要同时使用多个规则集，可以使用数组的方式将多个规则集合并到一起：

{
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:react/recommended",
    "plugin:vue/recommended"
  ]
}

如果需要定义自己的规则集，可以使用相对路径或绝对路径指定规则集的位置:

{
  "extends": "./path/to/my-rule-set"
}

extends 的优先级是从低到高的，后面的规则会覆盖前面的规则，最终以最后一个规则集为准；而当一个规则在多个规则集中定义时，后边的会覆盖前面的。例如：

// eslint-config-a.js
module.exports = {
  rules: {
    'no-console': 'off',
    'no-alert': 'error'
  }
};

// eslint-config-b.js
module.exports = {
  extends: ['eslint-config-a'],
  rules: {
    'no-console': 'error',
    'no-debugger': 'warn'
  }
};

eslint-config-b 中，no-console使用error，而不是off。

settings

一个可选的顶层属性，它可以用来配置一些额外的、自定义的信息，供插件和规则使用。它的值是一个对象，可以包含多个属性。下面是一些常用的 settings 属性及其作用：

• react：该属性用于配置 React 相关的环境和选项。具体来说，它可以包含以下属性：
  • version：React 的版本号，如果不设置该属性，则插件会尝试自动检测 React 的版本。
  • pragma：JSX 的注释语法，如果你使用了类似于 /** @jsx h */ 的注释来指定 JSX 的转换函数，则需要设置该属性。
  • fragment：使用 Fragment 组件的名称，如果你使用了 Fragment 组件，则需要设置该属性。
  • linkComponents：配置自定义组件链接的规则，用于解决组件在某些情况下无法链接的问题。
• import/resolver：该属性用于配置导入模块时的解析器，通常用于解决路径问题。具体来说，它可以包含以下属性：
  • node：该属性用于解析 Node.js 模块。
  • webpack：该属性用于解析 Webpack 模块。
  • typescript：该属性用于解析 TypeScript 模块。
  • alias：配置模块路径的别名，用于解决路径问题。
  • extensions：配置模块的扩展名，用于解决模块文件类型的问题。
• polyfills：该属性用于配置一些需要在代码中手动引入的 Polyfill，通常用于解决兼容性问题。
• react-native/style-sheet-object-names：该属性用于配置 React Native 中使用的 StyleSheet 对象名称。
• jest：该属性用于配置 Jest 测试框架相关的信息。
• svelte3：该属性用于配置 Svelte 3 相关的信息。

等等...

新配置文件

ESLint将在 9.0版本启用新的配置文件格式eslint.config.js，其换了一种新的配置方式，示例如下：

export default [
  {
    rules: {
      semi: "error",
      "prefer-const": "error"
    }
  },
  {
    files: ["src/**/*.js"],
    ignores: ["**/*.config.js"],
    rules: {
      semi: "off"
    }
  }
]

具体新的动向，可以关注官网的更新。

发布npm

建立一个文件仓库：

index.js写入配置：

package.json写入：

登录npm：

npm login --registry=http://registry.npm.pre.xxx.com

执行发布脚本（patch为例）：

npm run publish:patch

在前端项目中使用配置：

剩余的配置husky等工作，就可以参见我之前的文章：前端项目配置 git hook + prettier + eslint

总结：eslint配置文件单独封装在一个独立库中，便于扩展和维护升级，灵活性更强，适合前端多页面应用或者微服务应用的场景。

至此，前端校验工具 eslint就配置完成啦！