基于ESLint+Prettier+Stylelint+git提交规范的团队规范指南

crazy-三笠

已于 2023-11-06 17:13:38 修改

阅读量343

点赞数 1

分类专栏：前端 ESLint 代码规范文章标签：前端代码规范 git

于 2023-11-03 14:07:58 首次发布

本文链接：https://blog.csdn.net/qq_52839794/article/details/134195597

版权

前端同时被 3 个专栏收录

3 篇文章 0 订阅

订阅专栏

ESLint

1 篇文章 0 订阅

订阅专栏

代码规范

1 篇文章 0 订阅

订阅专栏

一、ESlint

1、什么是ESLint

EsLint是一个用于识别和报告在 ECMAScript/JavaScript 代码中发现的模式的工具，目的是使代码更加一致，并避免错误。总的来说这就是一个用于代码规范的工具。

2、使用ESLint的好处

对于个人而言它可以避免代码中的语法bug、结构性问题，还能格式化代码和自动美化代码。

对开发团队而言能够统一代码风格，进而降低维护成本，能直接有效的约束团队成员使用统一规范。

3、安装与配置

3.1、安装ESLint

npm install eslint 或 npm install eslint --save-dev

前者是在运行中使用，如果代码不符合规范，它可能会导致运行时错误或异常。

后者是在开发过程进行检查，语法不错误就不影响运行。

3.2、Vscode安装ESLint的拓展工具

3.3、生成ESLint配置文件

npx eslint --init

会出现如下配置项进行选择

How would you like to use ESLint?

//仅检查语法

To check syntax only

//检查语法和问题

To check syntax and find problems

//检查语法、发现问题并强制执行代码

To check syntax, find problems, and enforce code style

What type of modules does your project use?

//使用ES6的模块语法

JavaScript modules (import/export)

//使用CommonJS模块规范

CommonJS (require/exports)

//使用其他方式

None of these

//您的项目使用哪个框架？React、Vue.js和其他。

Which framework does your project use?

React

Vue.js

None of these

//您的项目是否使用ts

Does your project use TypeScript? » No / Yes

//您的代码在哪里运行？Browser和Node

Where does your code run?

Browser

Node

//您希望配置文件的格式是什么？JavaScript、YAML和JSON。

What format do you want your config file to be in?

JavaScript

YAML

JSON

//你想要通过哪种方法定义你的代码风格

How would you like to define a style for your project?

//使用流行的代码风格指南
Use a popular style guide

//回答关于你的代码风格的问题
Answer questions about your style

//检查你的 JavaScript 文件
Inspect your JavaScript file(s)

在完成上述的选择后会创建一个配置文件.eslintrc.js（类似如下配置，不同选择配置文件不一样）

module.exports = {
    "env": {
        "browser": true,
        "es2021": true
    },
    "extends": [
        "eslint:recommended",
        "plugin:@typescript-eslint/recommended",
        "plugin:react/recommended"
    ],
    "overrides": [
        {
            "env": {
                "node": true
            },
            "files": [
                ".eslintrc.{js,cjs}"
            ],
            "parserOptions": {
                "sourceType": "script"
            }
        }
    ],
    "parser": "@typescript-eslint/parser",
    "parserOptions": {
        "ecmaVersion": "latest",
        "sourceType": "module"
    },
    "plugins": [
        "@typescript-eslint",
        "react"
    ],
    "rules": {
    }
}

3.4、配置文件

配置文件是 ESLint 最主要的配置方式。ESLint 配置文件支持多种格式，同一目录下，ESLint 按 .eslintrc.js, .eslintrc.cjs, .eslintrc.yaml, .eslintrc.yml, .eslintrc.json, package.json 下的 eslintConfig 字段 的顺序查找配置，相同目录下只有一个配置文件会生效。下面是.eslintrc.js的相关配置及其作用。

// .eslintrc.js
module.exports = {
  // 规则配置
  rules: {
    // 可以根据需要启用、禁用和自定义规则
    'rule-name': 'error',
    'other-rule': 'warn',
  },
  
  // 解析器配置
  parser: '@babel/eslint-parser', // 指定使用的解析器
  //指定直接传递给解析器上的 parse() 或 parseForESLint() 方法的其他选项的对象。
  parserOptions: {
    ecmaVersion: 2021, // ECMAScript版本
    sourceType: 'module', // 模块类型（'script' 或 'module'）
    ecmaFeatures: {
      jsx: true, // 启用JSX支持
    },
  },
  
  // 插件配置
  plugins: ['plugin-name'], // 配置要使用的插件
  
  // 扩展配置
  extends: [
    'eslint:recommended', // 使用推荐的ESLint规则
    'plugin-name/recommended', // 使用指定插件的推荐规则
  ],
  
  // 环境配置
  env: {
    browser: true, // 浏览器环境
    node: true, // Node.js环境
    es6: true, // 启用ES6全局变量
  },
  
  // 全局变量配置
  globals: {
    // 可以添加项目中使用的全局变量，避免ESLint报错
    globalVar: 'readonly',
  },
  
  // 文件过滤器
  ignorePatterns: ['node_modules/', 'dist/'], // 忽略指定的文件或目录
  
  // 其他配置
  settings: {
    // 自定义全局变量
    'import/resolver': {
      node: {
        extensions: ['.js', '.jsx'],
        paths: ['src'], // 自定义模块解析路径
      },
    },
  },
  
  // 覆盖特定文件或目录的配置
  overrides: [
    {
      files: ['test/**/*.js'], // 匹配要覆盖的文件
      rules: {
        'no-console': 'off', // 关闭在测试文件中禁用控制台的规则
      },
    },
  ],
  
  // 指定 ESLint 配置文件的根目录
  root: true,
  
  // 禁用在 JavaScript 文件中使用注释行内配置 ESLint 规则
  noInlineConfig: true,
  
  // 在使用了 eslint-disable 注释后报告未使用的禁用指示
  reportUnusedDisableDirectives: true,
  
  // 配置要忽略的文件和目录的匹配模式
  ignore: [
    'node_modules/',
    'dist/',
  ],
};

以上是ESLint配置文件的相关配置，各位可以根据自己的需要进行配置，以满足项目的具体要求。

这些配置都可于官方文档中找到，以下我列举几个常用的配置项及其对应参考地址。

rules配置：规则参考 - ESLint 中文网 (nodejs.cn)

插件配置：配置插件 - ESLint 中文网 (nodejs.cn)

二、 Prettier

1、什么是Prettier

Prettier 是一个代码格式化工具，它可以自动调整代码的缩进、换行和其他样式规范，以使代码风格保持一致。它支持多种编程语言（如 JavaScript、TypeScript、CSS、HTML 等），并且易于集成到各种开发环境和工作流中。

简单说，这个东西它可以一键帮你把代码按规定的格式进行调整美化，以使代码符合对应的规范要求。

2、使用Prettier的好处

Prettier提供了一致的代码风格、提高了开发效率，并减少了代码审查中的样式讨论。它易于配置和集成，适用于各种编程语言和开发环境，是一个值得推荐使用的工具。

3、安装与配置

3.1 VScode插件安装

直接在VScode安装以下插件即可

然后安装如下步骤进行配置即可实现保存自动格式化文件

1、确保已经在 VS Code 中安装了 Prettier 插件。可以在扩展商店搜索 "Prettier - Code formatter" 并安装。

2、打开 VS Code 的用户设置。可以通过点击菜单栏的 "文件"（File） -> "首选项"（Preferences）-> "设置"（Settings）或使用快捷键 "Ctrl + ，"（Windows/Linux）或 "Command + ，"（Mac）来打开设置。

3、在设置页面的搜索栏中输入 "format on save"，找到 "Editor: Format On Save" 选项。勾选 "Editor: Format On Save" 选项，确保其值为 true。这样当你保存文件时，Prettier 将自动对代码进行格式化。

4、（可选）如果你希望在保存时使用 Prettier 进行格式化而不是其他格式化工具，可以添加下面的配置项：

"editor.defaultFormatter": "esbenp.prettier-vscode"

可以选择其他的 Prettier 相关配置项进行个性化设置，如 "prettier.printWidth"、"prettier.tabWidth" 等。

完成以上设置后，每次保存文件时，Prettier 将会自动对代码进行格式化。这样可以确保代码的一致性和可读性，提高开发效率。

3.2 作为依赖安装进项目中

在终端输入以下代码进行安装

npm install prettier -D

4、配置文件

在项目根目录新建一个.prettierrc的文件，格式为json

{
  "printWidth": 80, // 指定单行代码长度，超过该长度将会进行换行，默认值为 80
  "tabWidth": 2, // 指定缩进的空格数，默认值为 2
  "useTabs": false, // 是否使用制表符进行缩进，默认为 false，表示使用空格进行缩进
  "semi": true, // 是否在语句末尾添加分号，默认为 true
  "singleQuote": false, // 是否使用单引号，默认为 false，表示使用双引号
  "quoteProps": "as-needed", // 对象属性是否使用引号包裹，默认为 "as-needed"，表示只有必要时才会添加引号
  "trailingComma": "none", // 多行数组或对象最后一个元素后是否添加逗号，默认为 "none"，表示不添加
  "bracketSpacing": true, // 对象字面量中的花括号是否添加空格，默认为 true
  "arrowParens": "avoid" // 箭头函数的参数是否添加圆括号，默认为 "avoid"，表示只有一个参数时省略圆括号
}

以上为prettier的相关配置，可根据项目需要进行自行调整

三、Stylelint

1、什么是Stylelint

Stylelint 是一个强大、先进的 CSS 代码检查器，可以帮助你规避 CSS 代码中的错误并保持一致的编码风格。

2、使用Stylelint的好处

1、提高代码质量：Stylelint是一款用于检查CSS代码的工具，可以帮助开发者找出代码中的潜在问题、错误和不规范的写法。通过使用StyleLint，开发者可以在编写CSS代码时遵循一些固定的规则和标准，从而提高代码的质量。

2、统一代码风格：Stylelint支持自定义规则集，可以根据项目需要进行相应的配置。通过统一代码风格，可以让团队成员之间的代码风格更加一致，便于后续代码的维护和修改。

3、提高代码可读性：Stylelint可以对代码进行格式化，使其更加易读、易懂。通过规范的代码格式，可以使代码更容易被其他人理解和阅读，从而提高代码可读性。

4、简化代码维护：Stylelint可以自动修复一些问题，例如错误的缩进、空格等等。通过自动修复这些问题，可以减少手动修复的时间，从而简化代码维护的过程。

3、安装与配置

3.1 VScode插件安装

打开VSCode，进入扩展面板（快捷键为Ctrl+Shift+X或者Cmd+Shift+X），搜索Stylelint插件。
选择Stylelint插件并进行安装。
安装完成后，在VSCode的设置（快捷键为Ctrl+,或者Cmd+,）中搜索stylelint.enable，将其设置为true，以启用Stylelint插件。
在VSCode的设置中搜索stylelint.config，指定Stylelint配置文件的路径。如果你的配置文件为.stylelintrc.json，则可以设置为：

{ "stylelint.config": ".stylelintrc.json" }

通过安装Stylelint插件，你可以在VSCode中方便地使用Stylelint来检查你的CSS代码，提高代码规范性和可维护性。

3.2 作为依赖安装进项目中

在终端输入以下代码进行stylelint（核心包）和stylelint-config-standard（StyleLint推荐标准配置）的安装

npm install stylelint stylelint-config-standard --save-dev

在根目录下创建名为 .stylelintrc.js 的文件用于放置StyleLint的配置信息，可以添加如下内容

module.exports = {
  extends: [
    'stylelint-config-recommended',
    'stylelint-config-prettier'
  ], // 继承基本配置和Prettier插件的配置

  plugins: [
    'stylelint-order',
    'stylelint-declaration-block-no-ignored-properties'
  ], // 加载自定义插件

  rules: {
    'color-hex-case': 'lower', // 颜色值使用小写字母
    'color-hex-length': 'long', // 颜色值使用长格式
    'font-family-name-quotes': 'always-where-recommended', // 字体名称使用引号
    'function-comma-newline-after': 'always-multi-line', // 多行函数逗号后面必须换行
    'function-comma-space-after': 'always-single-line', // 单行函数逗号后面必须空格
    'function-name-case': 'lower', // 函数名称使用小写字母
    'function-url-quotes': 'always', // 函数URL使用引号
    'max-nesting-depth': 3, // 最大嵌套深度为3
    'no-empty-source': true, // 不允许空的样式文件
    'order/properties-order': [], // CSS属性排序规则
    'property-no-unknown': [ // 不允许未知属性
      true,
      {
        ignoreProperties: ['composes']
      }
    ],
    'selector-max-id': 0, // 不允许使用ID选择器
    'selector-pseudo-element-no-unknown': [ // 不允许未知的伪元素
      true,
      {
        ignorePseudoElements: ['v-deep']
      }
    ],
    'selector-type-no-unknown': [ // 不允许未知的元素类型选择器
      true,
      {
        ignoreTypes: ['/^v-/']
      }
    ]
  }
}

以上为Stylelint的相关配置，可根据项目需要进行自行调整。

四、git提交规范（commitlint+lint-staged+husky）

1、Commitlint

1.1 什么时Commitlint

在我们开发完成后提交代码时，通常都需要填写提交说明，此提交说明用于git查看历史提交时使用直接的展现每次提交对于项目的更改，为了禁止不符合规范的提交，我们就需要采用一些工具，只有当开发者编写了符合规范的提交说明才能够进行提交。而 Commitlint 就是这样一种工具，通过结合 husky 一起使用，可以在开发者进行 commit 前就对提交说明进行检查，只有符合规范，才能够进行 commit。

1.2 Commitlint的安装与配置

使用npm安装Commitlint

npm install @commitlint/cli @commitlint/config-conventional --save-dev

安装完成后再根目录创建.commitlintrc.js文件进行配置。

module.exports = {
    extends: ['@commitlint/config-conventional'],
};

2、Husky

2.1 什么是Husky

在谈Husky需要先了解一下Git Hook在客户端部分的一些操作，主要分为以下这四种：

pre-commit：在代码提交前进行的操作，比如检查相关规范，检查语法等，用于防止提交错误的代码。

prepare-commit-msg：在你写commit信息之前，可以自动设置默认的commit信息，比如添加分支名称、任务ID等，方便你写commit信息。

commit-msg：在你提交commit信息之前，可以自动检查commit信息是否符合规范，比如检查是否包含必要的标识、长度限制等，确保commit信息的规范性。

post-commit：在你提交完代码之后，可以让计算机自动执行一些后续操作，比如自动推送代码到远程仓库，方便你管理代码。

在了解完以上的信息之后，我们来介绍一下Husky——Git Hook工具。主要用于配置和管理Git Hook脚本。它为开发者提供了一种简单的方式，在项目中添加和管理Git Hook脚本，无需手动编写和维护。

Husky主要作用在Git Hook的pre-commit、commit-msg等部分。它可以帮助你在项目中快速设置和执行Git Hook脚本，使得你可以在代码提交、合并等操作中加入额外的检查和验证。它与pre-commit、commit-msg等Git Hook脚本结合使用，让你可以在代码提交前运行代码格式化工具、静态代码分析工具、单元测试等，以确保提交的代码质量。

2.2 Husky的安装与配置

使用npm安装Husky

npm install husky --save-dev

在安装完成后需要对 package.json 文件进行配置

"scripts": {
    "prepare": "husky install",
},

在配置完成后在终端输入如下代码

npm run prepare

指令执行成功后会在项目根目录下面生成一个 .husky 目录，该目录下有一个 _ 目录。

然后在终端输入如下代码创建 commit-msg 文件

npx husky add .husky/commit-msg 'npx --no -- commitlint --edit "$1"'

该文件的作用是 git commit 前执行一下 npx --no -- commitlint --edit $1 指令，对 commit 的注释进行校验。

然后输入以下代码创建 pre-commit 文件

npx husky add .husky/pre-commit "npm run lint-staged"

该文件的作用主要是用于在git commit前执行 npm run lint-staged 指令，对代码进行规范的校验，不符合规范就终止commit。

然后在package.json加入如下代码（ps：要在ESLint和Stylelint安装配置好后进行）

  "lint-staged": {
    "src/**/*.{js,ts,vue}": "eslint --fix --ignore-path .eslintignore",
    "src/**/*.{less,sass,css,vue}": "stylelint --fix --ignore-path .eslintignore"
  }

但是如果只有Husky的话，每次提交代码都会对所有文件运行Lint检查，如果项目体量大，那所耗费的时间成本太大了，为了解决这个问题，我们需要结合下面的工具Lint-staged进行使用。

3、Lint-staged

3.1 什么是Lint-staged

Lint-staged 可以在我们运行 ESlint 或 Stylelint 命令时，可以通过设置指定只检查我们通过 git add 添加到暂存区的文件，可以避免我们每次检查都把整个项目的代码都检查一遍，从而提高效率。

其次，Lint-staged 允许指定不同类型后缀文件执行不同指令的操作，并且可以按步骤再额外执行一些其它 shell 指令。

3.2 安装和配置Lint-staged

使用npm安装Lint-staged

npm install lint-staged --save-dev

在安装完 Lint-staged后在package.json加入如下代码进行配置（ps：要在husky，ESLint 和 Stylelint安装配置完后操作）


 "scripts": {
    "prepare": "husky install",
 },
 "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
 },

"lint-staged": {
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.json": [
      "prettier --write"
    ],
    "*.vue": [
      "eslint --fix",
      "prettier --write",
      "stylelint --fix"
    ],
    "*.{scss,less,html}": [
      "stylelint --fix",
      "prettier --write"
    ],
    "*.md": [
      "prettier --write"
    ]
  }

当我们执行 git commit 时，就会触发 husky 的 pre-commit 钩子，调用 lint-staged 命令。而 lint-staged会根据配置对不同类型的文件进行规范检查。

五、配置实例

1、ESLint配置实例

以下是团队的ESLint的配置实例

//.eslintrc.js
module.exports = {
  //指定使用 @typescript-eslint/parser 解析器，以解析 TypeScript 代码。
  parser: '@typescript-eslint/parser',
//继承了一些预设的规则集，提供了一系列的规则配置，可以帮助你更好地检测和修复代码中的问题。
  extends: ['plugin:@typescript-eslint/recommended', 'react-app', 'plugin:prettier/recommended'],
  //引入了一些插件,提供了额外的规则和功能，可以进一步增强 ESLint 的能力。
  plugins: ['@typescript-eslint', 'react'],
  //定义了一些具体的规则配置。
  rules: {
    //使用 Prettier 进行代码格式化，并将格式不一致的代码视为错误。
    'prettier/prettier': 'error',
    //禁止未使用的变量。
    '@typescript-eslint/no-unused-vars': 'error',
    //允许使用 any 类型。
    '@typescript-eslint/no-explicit-any': 'off',
    //允许使用 TypeScript 的注释语法。
    '@typescript-eslint/ban-ts-comment': 'off',
    //允许使用全局变量。
    'no-restricted-globals': 'off',
    //允许使用非空断言操作符（!）。
    '@typescript-eslint/no-non-null-assertion': 'off',
  },
};

用以下文件来设置规则忽略的文件

//.eslintignore
config/
node_modules/

2、prettier配置实例

以下是团队的prettier配置实例

// .prettierrc.js
module.exports =  {
    "printWidth": 120,
    "semi": true,
    "singleQuote": true,
    "tabWidth": 2,
    "endOfLine": 'auto'
  };

3、Stylelint配置实例

以下是团队的Stylelint配置实例

//.stylelintrc.js
module.exports = {
    processors: [],
    plugins: ['stylelint-order'],
    extends: [
        "stylelint-config-standard",
        "stylelint-config-css-modules"
    ],
    rules: {
        "indentation": 2,
        "no-descending-specificity": null,
        "selector-class-pattern": null
     }
}

4、git提交规范配置

以下是团队的git提交规范配置实例

//package.json
"scripts": {
    "lint": "eslint --ext .js,.jsx,.ts,.tsx ./src",
    "lint:fix": "eslint --ext .js,.jsx,.ts,.tsx ./src --fix",
    "lint:less": "stylelint src/**/*.less --custom-syntax postcss-less",
    "lint:less:fix": "stylelint src/**/*.less --fix  --custom-syntax postcss-less",
    "prepare": "husky install"
  },
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.{ts,tsx}": [
      "npm run lint:fix",
      "git add"
    ],
    "*.less": [
      "npm run lint:less:fix",
      "git add"
    ]
  },
  "devDependencies": {
    "husky": "^8.0.3"
  }