在 React-CRA 应用中配合 VSCode 使用 ESLint 实践前端代码规范

更新时间：2019-01-22
React.js create-react-app 项目 + VSCode 编辑器 + ESLint 代码检查工具 + Airbnb 编码规范

前言

为什么要使用 ESLint

在项目开发过程中，编写符合团队编码规范的代码是尤为重要的，程序首先是给人看的，其次才是给机器去执行。我们在开发工作中，代码维护会占很大的比重，很多时候我们还需要阅读他人的代码，如果没有一个统一的编码规范，将会给我们的工作带来很大的困扰。

因此，我们期望在开发过程中遵循统一的编码规范，以实现避免基本语法错误、代码格式化、规避一些不推荐的用法等目的，最大程度的保证代码的可读性和正确性。通常每个团队都会制定适合自己的编码规范和代码风格，但是仅仅制定规范是不够的，还需要借助代码检查工具来强制推行团队的编码规范，比如 ESLint 代码检查工具。

本文会介绍一种 ESLint 的配置方案，但本文关于 ESLint 的配置是基于一定的开发环境的，偏重于实际应用，并非 ESLint 本身的介绍。这里对 ESLint 的配置基于以下环境：

• React.js create-react-app 脚手架项目
• 使用 VSCode 编辑器
• 基于 Airbnb 编码规范

相关链接

1. ESLint 代码检查工具
   ESLint（中文） 是一个开源的 JavaScript 代码检查工具，由 Nicholas C. Zakas 于2013年6月创建。

   JavaScript 是一个动态的弱类型语言，在开发中比较容易出错。因为没有编译程序，为了寻找 JavaScript 代码错误通常需要在执行过程中不断调试。像 ESLint 这样的可以让程序员在编码的过程中发现问题而不是在执行的过程中。

   ESLint 的初衷是为了让程序员可以创建自己的检测规则。ESLint 的所有规则都被设计成可插入的。ESLint 的默认规则与其他的插件并没有什么区别，规则本身和测试可以依赖于同样的模式。为了便于人们使用，ESLint 内置了一些规则，当然，你可以在使用过程中自定义规则。

2. Create-React-App 应用
   Create React App 是 React 官方支持的创建单页面 React 应用的方式，通过 create-react-app 脚手架命令可以快速创建一个 React 应用，免去了我们自己配置 webpack 的麻烦，我们这次 ESLint 的配置方案就是基于 create-react-app 项目的。
3. VSCode 编辑器
   VSCode 是微软的良心之作，是一个轻量且强大的代码编辑器，支持 Windows 和 Linux。内置 JavaScript、TypeScript 和 Node.js 支持，而且拥有丰富的插件生态系统，还可以通过安装插件来支持 C++、C#、Python、PHP 等其他语言，堪称开发的利器。插件扩展：Extensions for the Visual Studio family of products。
4. Airbnb 编码规范
   Airbnb JavaScript Style Guide 是独角兽公司 Airbnb 内部的 JavaScript 编码规范，该项目是 Github 上很受欢迎的一个开源项目，在前端开发中使用广泛，本文的 ESLint 配置规则就是以Airbnb JavaScript 编码规范(2.0) 和 Airbnb React/JSX 编码规范 作为基础的。

具体配置方法

在 VSCode 中安装 ESLint 扩展

在 VSCode 扩展面板搜索 ESLint，找到安装最多的那个安装即可，安装完成之后需要 重新加载 以激活扩展，但想要让扩展进行工作，我们还需要进行 ESLint 的安装配置。

创建 CRA 项目

我们的配置方案是基于 CRA 脚手架项目进行测试的，因此我们要先创建一个 CRA 项目，具体方法详见官方文档：Create React App。

创建的 CRA 项目文件组织结构如下：

my-app
  ├── README.md
  ├── node_modules
  ├── package.json
  ├── .gitignore
  ├── public
  │   ├── favicon.ico
  │   ├── index.html
  │   └── manifest.json
  └── src
      ├── App.css
      ├── App.js
      ├── App.test.js
      ├── index.css
      ├── index.js
      ├── logo.svg
      └── serviceWorker.js

安装 ESLint

ESLint 可以选择进行本地安装：

npm install eslint --save-dev

也可以进行全局安装：

npm install -g eslint

一般推荐进行全局安装，使其可以作用于我们所有的项目。具体请参见 eslint-npm 文档。

创建 ESLint 配置文件

ESLint 安装完成之后，我们需要创建一个配置文件，为了详细演示 ESLint 是如何在实际项目中工作的，我们接下来的操作都在我们上面已经创建的 CRA 脚手架项目中进行，且先不考虑 Airbnb 编码规范的使用，而是先创建一个较为常见的自定义代码风格。

我们在创建的 my-app 项目下执行 cmd 命令 eslint --init，根据提示我们选择通过 Answer questions about your style 的方式创建一份自定义的代码规范，下图是一个示例，具体可根据项目需要进行配置：

这样我们就已经创建了一个自定义的 ESLint 配置文件，可以看到在 my-app 项目中生成了一个名为 .eslintrc.js 的文件，其中的规则就是根据我们上图中的选择进行设定的，具体内容如下：

/* .eslintrc.js */
  module.exports = {
      "env": {
          "browser": true,
          "commonjs": true,
          "es6": true
      },
      "extends": "eslint:recommended",
      "parserOptions": {
          "ecmaFeatures": {
              "jsx": true
          },
          "ecmaVersion": 2018,
          "sourceType": "module"
      },
      "plugins": [
          "react"
      ],
      "rules": {
          "indent": [
              "error",
              4
          ],
          "linebreak-style": [
              "error",
              "windows"
          ],
          "quotes": [
              "error",
              "single"
          ],
          "semi": [
              "error",
              "always"
          ]
      }
  };

至此，我们在 VSCode 中打开 my-app 项目，可以发现 ESLint 扩展已经可以正常工作了，ESLint 会自动检测语法错误，并高亮显示，同时在 VSCode 编辑器的问题窗口会输出相应的错误信息。

忽略特定的文件和目录

你可以通过在项目根目录创建一个 .eslintignore 文件告诉 ESLint 去忽略特定的文件和目录。具体请参见：Ignoring Files and Directories。

例如：把下面 .eslintignore 文件放到当前工作目录里，将忽略项目根目录下的 node_modules，bower_components 以及 build/ 目录下除了 build/index.js 的所有文件。

# /node_modules/* and /bower_components/* in the project root are ignored by default

  # Ignore built files except build/index.js
  build/*
  !build/index.js

重要：注意代码库的 node_modules 目录，比如，一个 packages 目录，默认情况下不会被忽略，需要手动添加到 .eslintignore。

设置 autoFixOnSave

经过以上步骤操作之后，ESLint 扩展已经正常工作了，并且可以根据错误提示手动修复检测到的错误，但是这样显然是低效和繁琐的，这个时候就需要配置 ESLint 扩展插件的自动修复功能了。

在 VSCode 中依次点击 文件-->首选项-->设置，打开 settings.json 文件，在设置中搜索 eslint，会发现 ESLint 扩展插件的自动修复功能是关闭的，我们在右侧的用户设置中对此项进行修改，将其设置为："eslint.autoFixOnSave": true,，这样 ESLint 扩展插件的自动修复功能就打开了。

此时，我们再次打开错误页面，执行保存（Ctrl+s）操作，就会发现 eslint 的错误可以自动修复了，如果当前页面错误较多的话，可能需要多次执行 Ctrl+s。

使用 Airbnb 编码规范

上面我们已经使 ESLint 在我们的项目中正常工作了，但使用的代码风格是我们自定义的，有时候我们希望使用一些大厂的比较成熟的代码规范，比如 Airbnb JavaScript Style，接下来我们就将自定义的 ESLint 配置改为使用 Airbnb 编码规范配置。

首先，我们需要安装 2 个 npm 依赖包：

1. babel-eslint，增强语法识别能力

   babel-eslint allows you to lint ALL valid Babel code with the fantastic ESLint.

   $ npm i babel-eslint

2. eslint-config-airbnb，Airbnb 提供的支持 ECMAScript 6+ 和 React 的 ESLint rules，包括 eslint eslint-plugin-import eslint-plugin-react 以及 eslint-plugin-jsx-a11y。

   Our default export contains all of our ESLint rules, including ECMAScript 6+ and React. It requires eslint, eslint-plugin-import, eslint-plugin-react, and eslint-plugin-jsx-a11y. If you don't need React, see eslint-config-airbnb-base.

   // If using npm 5+, use this shortcut
   $ npx install-peerdeps --dev eslint-config-airbnb

然后我们要修改 .eslintrc.js 文件，以使用我们安装的 Airbnb 编码规范，修改后内容如下：

/* .eslintrc.js */
  module.exports = {
      "env": {
          "browser": true,
          "commonjs": true,
          "es6": true
      },
      "extends": "airbnb", // 使用 eslint-config-airbnb
      "parser": "babel-eslint", // 增强语法识别能力
      "parserOptions": {
          "ecmaFeatures": {
              "jsx": true
          },
          "ecmaVersion": 2017,
          "sourceType": "module"
      },
      "rules": {
          // 这里可以根据需要对 airbnb 的规则进行修改，此处仅为示例
          "linebreak-style": 0,
          "prefer-destructuring": 0,
          "prefer-const": 0,
          "one-var": 0,
          "comma-dangle": ['error', {
              arrays: 'only-multiline',
              objects: 'always-multiline',
              imports: 'only-multiline',
              exports: 'only-multiline',
              functions: 'ignore',
          }],
          "no-console": 1,
          "import/prefer-default-export": 0,
          "import/no-extraneous-dependencies": [2, {'devDependencies': true}],
          "react/prop-types": 1,
          "react/forbid-prop-types": 0,
          "react/jsx-filename-extension": [2, {extensions: ['.js', '.jsx', '.tsx']}],
          "jsx-a11y/anchor-is-valid": 0,

          // VSCode 的 ESLint 扩展插件暂时无法正确修复这条规则带来的错误
          "react/jsx-one-expression-per-line": 0,
      }
  };

至此，我们完成了在 React-CRA 应用中配合 VSCode 使用 ESLint 的全部配置。

错误信息

在修改 .eslintrc.js 文件以使用Airbnb 编码规范（eslint-config-airbnb）的过程中，发现 VSCode 的 ESLint 扩展插件对其中的有些规则不能正确的自动修复，比如：

// One JSX Element Per Line
  // https://github.com/yannickcr/eslint-plugin-react/blob/843d71a432baf0f01f598d7cf1eea75ad6896e4b/docs/rules/jsx-one-expression-per-line.md
  'react/jsx-one-expression-per-line': ['error', { allow: 'single-child' }],

查阅 eslint-config-airbnb 的文档发现，eslint-config-airbnb v17.1.0 版本修改了上面这条规则，具体可以参见：re-enabling jsx-one-expression-per-line allowing single children 以及 One JSX Element Per Line (react/jsx-one-expression-per-line)。

当前版本的 VSCode 的 ESLint 扩展插件无法正确修复这条规则带来的错误，由于暂时找不到其他解决方法，这里就先将这条规则关闭。

由此可见，随着 VSCode 或 ESLint 相关的插件和依赖包版本的变动，配置也会发生一些不可预期的变化，这里将用来测试的 CRA 脚手架项目的 package.json 文件内容附录如下；

/* package.json */
  {
    "name": "my-app",
    "version": "0.1.0",
    "private": true,
    "dependencies": {
      "babel-eslint": "^10.0.1",
      "react": "^16.7.0",
      "react-dom": "^16.7.0",
      "react-scripts": "2.1.3"
    },
    "scripts": {
      "start": "react-scripts start",
      "build": "react-scripts build",
      "test": "react-scripts test",
      "eject": "react-scripts eject"
    },
    "eslintConfig": {
      "extends": "react-app"
    },
    "browserslist": [
      ">0.2%",
      "not dead",
      "not ie <= 11",
      "not op_mini all"
    ],
    "devDependencies": {
      "eslint": "^5.3.0",
      "eslint-config-airbnb": "^17.1.0",
      "eslint-plugin-import": "^2.14.0",
      "eslint-plugin-jsx-a11y": "^6.1.1",
      "eslint-plugin-react": "^7.11.0"
    }
  }