零散专题16 代码检查和格式化

发表于 2017-12-05 更新于 2019-12-25 分类于其他阅读次数：

EditorConfig + ESLint + ESLint + Husky + Stylelint学习小结。

EditorConfig

为了保持项目中代码缩进风格的一致，可以使用.editorconfig文件，来定义和维护一致的编码风格，例如范缩进风格，缩进大小，Tab长度以及字符集等。一般情况会覆盖IDE本身的设置，所以放在项目的根目录中，提交到代码仓库进行维护。

.editorconfig中第一行用于指明.editorconfig文件的位置，[*]表明规则应用所有文件，可以针对不同文件（比如[*.md]）添加不同的规则，再下面是具体对应的规则

下面是我在项目中尝试用的一份.editorconfig文件，

root = true

[*]
# 缩进风格：空格
indent_style = space

# 缩进大小2
indent_size = 2

# 字符集utf-8
charset = utf-8

# 除去换行行首的任意空白字符
trim_trailing_whitespace = true

# 使文件以一个空白行结尾
insert_final_newline = true

[*.md]
trim_trailing_whitespace = false

没有加入的属性几个，比如定义换行符的end_of_line，可以取值lf、cr和crlf，更详细的介绍可以参考腾讯AlloyTeam的文章。

ESLint

Eslint是一个用来识别ECMAScript并且按照规则给出报告的代码检测工具，使用它可以避免低级错误和统一代码的风格。ESLint被设计为完全可配置的，一般使用配置文件来配置ESLint，在项目的根目录下创建.eslintrc.js

可以被配置的信息主要分为3类：

Environments：你的Javascript脚本将要运行在什么环境（如：Node，浏览器等）中。
Globals：执行代码时脚步需要访问的额外全局变量。
Rules：开启某些规则，也可以设置规则的等级。

安装

安装推荐局部安装：

1	npm i -D eslint

安装完毕后，接下来新建一个配置文件.eslintrc.js，或者使用如下的命令行来自动生成。

./node_modules/.bin/eslint --init

# 如果是全局安装的话可以执行
eslint --init

配置文件中的配置规则分为三种等级：

off或者0：关闭规则
warn或者1：打开规则，并且作为一个警告
error或者2：打开规则，并且作为一个错误

// .eslintrc.js
module.exports = {
  env: {
    browser: true,
    node: true,
  },
};

具体的配置规则非常多，具体见这里。

在Webstorm中使用

在Webstorm中配置ESLint，需要在Language & Frameworks → Javascript → Code Quality Tools → ESLint中进行配置，勾选Enable。

一般情况下下面的对应的配置和地址都会自动填好。

开启之后Webstorm就会在代码中对违反ESLint规则的代码进行高亮提示。

配合Vue项目使用

Vue Cli在创建项目时，可以选择是否启用ESLint，并且可以选择使用哪种扩展，基本上不需要自己再进行配置，但是如果需要自己手动配置时，可以自己安装eslint-plugin-vue这个插件

ESLint配置中的plugin和extend的区别是，extend提供的是ESLint现有规则的一些列预设，而plugin除了提供预设之外的自定义规则，当现有格式的代码（比如.vue）在ESLint的规则中没有对应的规则是，就需要借用插件来实现了

插件的安装有三种方式，推荐使用第一种：

vue add @vue/cli-plugin-eslint

npm install --save-dev eslint eslint-plugin-vue

yarn add -D eslint eslint-plugin-vue

对应的配置文件eslintrc.js：

module.exports = {
  extends: [
    // add more generic rulesets here, such as:
    // 'eslint:recommended',
    'plugin:vue/recommended'
  ],
  rules: {
    // override/add rules settings here, such as:
    // 'vue/no-unused-vars': 'error'
  }
}

规则分为Essential、Strongly Recommended和Recommended三个等级，具体的规则可以参考官网。

我在项目中使用的配置是：

// ESLint 中文文档：http://eslint.cn/docs/rules/
// eslint-plugin-vue: https://eslint.vuejs.org/
// 百度 EFE 团队使用的 eslint 配置：https://github.com/ecomfe/eslint-config/blob/master/index.js
// JavaScript 编码规范(百度): http://gitlab.baidu.com/fe/spec/blob/master/javascript.md#2-1
// Vue 组件代码规范(百度): http://gitlab.baidu.com/fe/spec/blob/master/vue.md#2-1
// iCode校验规则说明：http://bugbye.baidu.com/rules

module.exports = {
  'parser': 'vue-eslint-parser',
  'env': {
    'browser': true,
    'amd': true,
    'node': true
  },
  parserOptions: {
    'ecmaVersion': 8,
    'parser': 'babel-eslint',
    'sourceType': 'module'
  },
  'extends': ['plugin:vue/essential', ],
  'rules': {
    /* ---------------- 禁止 ---------------- */
    // 4个空格缩进
    'indent': ['error', 4, {
      'SwitchCase': 1, // switch 的 case 子句缩进4个空格
    }],
    // 只允许最大连续2行空行
    'no-multiple-empty-lines': ['error'],
    // 禁止不写分号
    'semi': ['error', 'always', {
      'omitLastInOneLineBlock': true
    }],
    // 使用单引号
    'quotes': ['error', 'single'],
    // Vue 模板标签开始、结束位置不能有空格，自闭合标签有空格
    'vue/html-closing-bracket-spacing': ['error', {
      'startTag': 'never',
      'endTag': 'never',
      'selfClosingTag': 'always',
    }],
    // Vue 模板结束标签
    'vue/html-closing-bracket-newline': ['error', {
      'singleline': 'never',
      'multiline': 'never',
    }],
    // Vue 模板标签对齐方式
    'vue/html-indent': ['error', 4, {
      'attribute': 1,
      'baseIndent': 1,
      'closeBracket': 0,
      'alignAttributesVertically': true,
      'ignores': []
    }],
    // Vue script 标签对齐
    'vue/script-indent': ['error', 4, {
      'baseIndent': 1,
      'switchCase': 1, // switch 的 case 子句缩进4个空格
    }],
    // Vue 模板标签必须成对出现
    'vue/html-end-tags': 'error',
    // 对象和数组字面量中，最后一个选项的逗号，多行时必须有，单行时不能用
    'comma-dangle': ['error', {
      'arrays': 'always-multiline',
      'objects': 'always-multiline',
      'imports': 'always-multiline',
      'exports': 'always-multiline',
      'functions': 'never',
    }, ],
    // 禁止在数组括号内出现空格
    'array-bracket-spacing': ['error', 'never'],
    // 禁止在对象的大括号内出现空格
    'object-curly-spacing': ['error', 'never'],
    // 禁止在对象字面量的键和冒号之间存在空格，要求在对象字面量的键和冒号之间存在至少有一个空格
    'key-spacing': ['error', {
      'beforeColon': false,
      'afterColon': true,
    }, ],
    /* ---------------- 建议 ---------------- */
    // 建议提交时不要出现alert, prompt 和 confirm,
    'no-alert': 'warn',
    // 建议提交时不要出现console
    'no-console': 'warn',
    // 建议提交时不要出现debugger
    'no-debugger': 'error',
    // 建议不要出现常量作为判断条件
    'no-constant-condition': 'warn',
    // 建议注释符要有空白隔开
    'spaced-comment': ['warn', 'always'],
    // 建议将操作符放到行首, 而不是行尾
    'operator-linebreak': ['warn', 'before'],
    // 建议代码列数不能超过120行
    'max-len': ['warn', 120],
    /* ---------------- 允许 ---------------- */
    // 允许if (!!foo) 这种形式
    'no-extra-boolean-cast': 'off',
    // 允许对函数声明进行覆盖赋值
    'no-func-assign': 'off',
    // 允许函数在不同的情况下返回不同类型的值
    'consistent-return': 'off',
    // 允许覆盖外部变量
    'no-shadow': 'off',
    // 允许使用下划线开头命名变量
    'no-underscore-dangle': 'off',
  },
  // 覆盖规则
  'overrides': [{
    // vue 文件的 intent 规则使用
    'files': ['*.vue'],
    'rules': {
      'indent': 'off',
    }
  }]
};

配合React项目使用

需要安装ESLint-plugin-React插件：

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

详细的规则参考官网。

下面是我的一份.eslintrc.js配置文件，在extends中使用这个插件：

module.exports = {
  extends: [
    'eslint:recommended',
    'plugin:react/recommended'
  ],
  plugins: [
    'reacte',
    'react-hooks'
  ],
  parserOptions: {
    sourceType: 'module',
    ecmaFeatures: {
      // 开启 JSX 支持
      jsx: true
    }
  }
  env: {
    jest: true,
    browser: true,
    node: true
  },
  settings: {
    react: {
      // React version. 'detect' automatically picks the version you have installed.
      // You can also use `16.0`, `16.3`, etc, if you want to override the detected value.
      'version': 'detect'
    }
  },
  globals: {
    // 这里填入你的项目需要的全局变量
    // 这里值为 false 表示这个全局变量不允许被重新赋值，比如：
    //
    // jQuery: false,
    // $: false
  },
  rules: {
    // 这里填入你的项目需要的个性化配置，比如：
    //
    // @fixable 一个缩进必须用两个空格替代
    'indent': [
      2,
      2,
      {
        // 强制 switch 语句中的 case 子句的缩进级别
        'SwitchCase': 1,
        // 要求三元表达式内的三元表达式不能有缩进
        'flatTernaryExpressions': true,
        // 对于 JSX 属性对其不进行约束，在下面的 react/jsx-indent-props 进行约束
        'ignoredNodes': ['JSXAttribute', 'JSXSpreadAttribute']
      }
    ],
    'semi': ['warn', 'always'],
    // JSX 的 children 缩进必须为两个空格
    'react/jsx-indent': [2, 2],
    // JSX 的 props 缩进必须为两个空格
    'react/jsx-indent-props': [2, 'first'],
    // JSX 自闭和标签结束位置
    'react/jsx-closing-bracket-location': [2, 'after-props'],
    // 禁止出现超过两行的连续空行
    'no-multiple-empty-lines': [2, { 'max': 2}],
    // 一行长度不应该超过120个字符
    'max-len': [2, 120],
    // React Hooks只能应用顶级函数和React函数中
    'react-hooks/rules-of-hooks': 'error',
    'react-hooks/exhaustive-deps': 'error',

    'no-unused-vars': 'warn',

    // no-debugger
    'no-debugger': process.env.NODE_ENV === 'production' ? 2 : 0
  }
};

也可以直接使用腾讯的AlloyTeam的ESLint规则（推荐），有详细的规则描述和示例，可以在此基础上进行定制。

使用时需要首先安装eslint、babel-eslint、eslint-config-alloy，这是AlloyTeam的ESLint规则的最基础的所需要安装的依赖

1	npm install -D eslint babel-eslint eslint-config-alloy eslint-plugin-react

并将以下内容复制到.eslintrc.js

module.exports = {
  extends: [
    'alloy',
    'alloy/react',
  ],
  env: {
    // 你的环境变量（包含多个预定义的全局变量）
    //
    // browser: true,
    // node: true,
    // mocha: true,
    // jest: true,
    // jquery: true
  },
  globals: {
    // 你的全局变量（设置为 false 表示它不允许被重新赋值）
    //
    // myGlobal: false
  },
  rules: {
    // 自定义你的规则
  }
};

AlloyTeam也有针对Vue项目、TypeScript项目、React+TypeScript项目的各种规则，可以按需选择。

需要注意的是，如果使用的Create React App脚手架工具来搭建React项目，由于它将默认的构建配置封装了起来，而ESLint仅仅开启了最基本的规则，更重要的是默认情况下，ESLint仅仅会在IDE中对违反规则的情况进行提示，并不会在构建时在终端的输出进行终端和提示。

如果这种情况可以满足需要，而只需要开启更多的规则，那么在.eslintrc.js中的extends中添加对应的规则集即可

但是如果要起到更强制性的提示作用（中断构建、终端提示），Create React App建议使用Prettier代替ESLint。如果要使用ESLint，那么就需要使用npm run eject，将配置文件吐出，按照AlloyTeam的提示进行配置即可。

配合TypeScript项目使用

由于ESLint默认使用Espree进行语法解析，无法识别TypeScript的某些语法，需要安装@typescript-eslint/parser替代默认的解析器

1	npm install --save-dev @typescript-eslint/parser

最后安装对应的规则插件@typescript-eslint/eslint-plugin

1	npm install --save-dev @typescript-eslint/eslint-plugin

对ESLint进行配置，在根目录下创建.eslintrc.js：

module.exports = {
  parser: '@typescript-eslint/parser',
  plugins: ['@typescript-eslint'],
};

上面提到了，AlloyTeam也有对应TypeScript的规则

安装和配置时直接按照下面的进行即可，已经包含了上面的安装和配置步骤

安装：

1	npm install --save-dev eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-config-alloy

配置文件：

module.exports = {
  extends: [
    'alloy',
    'alloy/typescript',
  ],
  env: {
    // 您的环境变量（包含多个预定义的全局变量）
    // Your environments (which contains several predefined global variables)
    //
    // browser: true,
    // node: true,
    // mocha: true,
    // jest: true,
    // jquery: true
  },
  globals: {
    // 您的全局变量（设置为 false 表示它不允许被重新赋值）
    // Your global variables (setting to false means it's not allowed to be reassigned)
    //
    // myGlobal: false
  },
  rules: {
    // 自定义您的规则
    // Customize your rules
  }
};

配合TypeScript + React项目使用（`.tsx`文件）

要检查React的.tsc文件，首先需要安装eslint-plugin-react：

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

然后在lint命令后面需要添加.tsx后缀：

{
  "scripts": {
    "eslint": "eslint src --ext .ts,.tsx"
  }
}

也可以使用AlloyTeam的ESLint规则的TypeScript React版本。

安装：

1	npm install --save-dev eslint typescript @typescript-eslint/parser @typescript-eslint/eslint-plugin eslint-plugin-react eslint-config-alloy

配置文件：

module.exports = {
  extends: [
    'alloy',
    'alloy/react',
    'alloy/typescript',
  ],
  env: {
    // Your environments (which contains several predefined global variables)
    //
    // browser: true,
    // node: true,
    // mocha: true,
    // jest: true,
    // jquery: true
  },
  globals: {
    // Your global variables (setting to false means it's not allowed to be reassigned)
    //
    // myGlobal: false
  },
  rules: {
    // Customize your rules
  }
};

ESlint对`Async`报错的解决方法

在ESlint配置文件中增加

1
2
3

parserOptions: {
  "ecmaVersion": 8,
}

Prettier

Prettier是一个流行的代码格式化工具，Webstorm的代码格式化就使用了这个插件。

一般情况下，ESLint会包含对代码格式的检查（比如缩进、结尾分号等），但是很多ESLint的插件（比如eslint-config-alloy）将所有样式相关的规则都剔除了。这是因为相比与ESLint中的代码格式规则，它提供了更少的选项，但是却更加专业。所以让ESLint来检查它更擅长的逻辑错误，使用Prettier中检查样式错误。

使用Prettier有两种方式，一种是结合ESLint使用（推荐），首先安装：

1	npm i -D prettier eslint-config-prettier eslint-plugin-prettier

其中prettier是Prettier插件的核心代码，eslint-config-prettier用来解决ESLint中的样式规范和Prettier中样式规范的冲突，以Prettier的样式规范为准，使ESLint中的样式规范自动失效，eslint-plugin-prettier用来将Prettier作为ESLint规范来使用

然后在项目的根目录下创建.prettierrc.js文件：

// 基于 AlloyTeam 使用的 .prettierrc.js 配置进行修改
module.exports = {
  // max 120 characters per line
  printWidth: 120,
  // use 2 spaces for indentation
  tabWidth: 2,
  // use spaces instead of indentations
  useTabs: false,
  // semicolon at the end of the line
  semi: true,
  // use single quotes
  singleQuote: true,
  // object's key is quoted only when necessary
  quoteProps: 'as-needed',
  // use double quotes instead of single quotes in jsx
  jsxSingleQuote: false,
  // no comma at the end
  trailingComma: 'none',
  // spaces are required at the beginning and end of the braces
  bracketSpacing: true,
  // end tag of jsx need to wrap
  jsxBracketSameLine: false,
  // brackets are required for arrow function parameter, even when there is only one parameter
  arrowParens: 'always',
  // format the entire contents of the file
  rangeStart: 0,
  rangeEnd: Infinity,
  // no need to write the beginning @prettier of the file
  requirePragma: false,
  // No need to automatically insert @prettier at the beginning of the file
  insertPragma: false,
  // use default break criteria
  proseWrap: 'preserve',
  // decide whether to break the html according to the display style
  htmlWhitespaceSensitivity: 'ignore',
  // lf for newline
  endOfLine: 'lf',
  // Whether or not to indent the code inside <script> and <style> tags in Vue files
  vueIndentScriptAndStyle: false,
};

关于规则的说明可以参考官方文档。

接着修改.eslintrc.js文件，引入Prettier（下面项目是TypeScript项目，其他项目配置参考eslint-config-prettier的文档：

module.exports = {
  parser: '@typescript-eslint/parser',
  extends: [
    'prettier/@typescript-eslint',
    "plugin:prettier/recommended",
  ],
  plugins: [
    '@typescript-eslint'
  ],
};

prettier/@typescript-eslint使得@typescript-eslint中的样式规范失效，遵循Prettier中的样式规范，plugin:prettier/recommended使用Prettier中的样式规范，且如果使得ESLint会检测prettier的格式问题，同样将格式问题以Error的形式抛出

这种形式的好处是，将Prettier与ESLint配合使用，当使用Lint-Staged进行检查时，只需要配置ESLint相关的命令即可。如果不符合规则，会进行提示，让你手动修改。

另一个方式就是单独使用Preitter，不使用eslint-plugin-prettier等插件，然后同样在.prettierrc.js中进行配置：

1	npm install --save-dev --save-exact prettier

这样的缺点是需要单独配置Prettier，优点是当代码风格不符合规则时，会直接按照配置的风格重新输出代码。当ESLint的规则与Prittier冲突时，还是通过上面提到的eslint-config-prettier来解决冲突

配合FECS使用

由于百度使用了统一制定的个性化的ESLint规则，可以直接使用fecs来检查代码

常规的使用方法不能满足每次提交时只检测对应改动的文件的要求，想要结合husky使用，需要新建一个.lintstagedrc文件：

module.exports = {
  // 使用 fecs 进行校验
  '*.js': filenames = > filenames.map(filename = > `fecs check '${filename}'--level = 2--rule = true--type = js, vue`)
  // '*.js': filenames => filenames.map(file => `eslint ${file}`)
};

将package.json的lint-staged的配置删除，这样每次提交时就会针对改动的文件进行配置。

它采用的JavaScript的编码规范在这里。

Fecs还提供了格式化的功能，fesc format。

stylelint

ESLint检查的JavaScript代码，对于CSS代码的检查就需要使用stylelint，它的使用和配置与ESLint非常类似，关于它的实践安可以参考企业微信的文章。

它的具体规则集在这里。预设的规则集有stylelint-config-recommended和stylelint-config-standard，前者只会检验可能导致错误的规则，后者在前者基础上还增加了60条规则，官方的选择建议是，如果使用了Prettier选择stylelint-config-recommended，如果希望统一样式的编写格式，那么可以选择stylelint-config-standard。在选择了某一种后，也可以在.stylelintrc.js中进行自定义的配置。

支持多种引入方式，一般常用的有下面两种

（1）命令行使用

安装：

1	npm install stylelint stylelint-config-standard -D

然后在.stylelintrc.js中进行配置：

// stylelint规则集：https://stylelint.io/user-guide/rules
// stylelint-config-standard扩展规则集：https://github.com/stylelint/stylelint-config-standard
module.exports = {
  'extends': 'stylelint-config-standard',
  'rules': {
    // add your onw rules
  }
};

这样在命令行中就可以对CSS文件进行校验：

1
2
3

stylelint "foo/*.css"
# 校验HTML文件中的 style 标签内的样式内容
stylelint "bar/*.html"

（2）与Webpack等构建工具配合使用

stylelint可以与各种构建工具配合使用，例如它提供了Webpack的插件stylelint-webpack-plugin，首先安装：

1	npm install stylelint stylelint-config-standard stylelint-webpack-plugin -D

然后在Webpack中配置

// vue.config.js

const StyleLintPlugin = require('stylelint-webpack-plugin');

module.exports = {
  lintOnSave: process.env.NODE_ENV !== 'production',
  configureWebpack: {
    plugins: [
      new StyleLintPlugin({
        files: ['src/**/*.{vue,htm,html,css,sss,less,scss,sass}'],
        lintDirtyModulesOnly: true,
        failOnError: false,
        failOnWarning: false
      })
    ]
  }
};

`lint-staged` + `husky`

使用lint-staged配合Husky，可以实现在Git某种操作前（一般是commit）仅检测有改动的代码。

首先进行安装：

npm install -D lint-staged husky;

// 这一行就可以安装husky和lint-stage，并且配置好husky。
npx mrm lint-staged

然后修改package.json，增加配置：

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{js,vue}": ["eslint", "stylelint"],
  },
}

这样在Commit之前就会使用ESLint进行校验。

如果配合Prettier使用，则可以自动格式化代码：

{
  "scripts": {
    "precommit": "lint-staged"
  },
  "lint-staged": {
    "src/**/*.js": ["prettier --write", "git add"]
  }
}