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

一、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(类似如下配置,不同选择配置文件不一样)

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``的相关配置及其作用。

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

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插件安装

  1. 打开VSCode,进入扩展面板(快捷键为Ctrl+Shift+X或者Cmd+Shift+X),搜索Stylelint插件。
  2. 选择Stylelint插件并进行安装。
  3. 安装完成后,在VSCode的设置(快捷键为Ctrl+,或者Cmd+,)中搜索stylelint.enable,将其设置为true,以启用Stylelint插件。
  4. 在VSCode的设置中搜索stylelint.config,指定Stylelint配置文件的路径。如果你的配置文件为.stylelintrc.json,则可以设置为:
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的配置信息,可以添加如下内容

js 复制代码
    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文件进行配置。

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 文件进行配置

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安装配置好后进行)

json 复制代码
      "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安装配置完后操作)

json 复制代码
 "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的配置实例

js 复制代码
    //.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',
      },
    };

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

js 复制代码
    //.eslintignore
    config/
    node_modules/

2、prettier配置实例

以下是团队的prettier配置实例

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

3、Stylelint配置实例

以下是团队的Stylelint配置实例

js 复制代码
    //.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提交规范配置实例

json 复制代码
    //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"
      }

相关推荐
喵叔哟10 分钟前
重构代码之取消临时字段
java·前端·重构
还是大剑师兰特1 小时前
D3的竞品有哪些,D3的优势,D3和echarts的对比
前端·javascript·echarts
王解1 小时前
【深度解析】CSS工程化全攻略(1)
前端·css
一只小白菜~1 小时前
web浏览器环境下使用window.open()打开PDF文件不是预览,而是下载文件?
前端·javascript·pdf·windowopen预览pdf
方才coding1 小时前
1小时构建Vue3知识体系之vue的生命周期函数
前端·javascript·vue.js
阿征学IT1 小时前
vue过滤器初步使用
前端·javascript·vue.js
王哲晓1 小时前
第四十五章 Vue之Vuex模块化创建(module)
前端·javascript·vue.js
丶21361 小时前
【WEB】深入理解 CORS(跨域资源共享):原理、配置与常见问题
前端·架构·web
发现你走远了1 小时前
『VUE』25. 组件事件与v-model(详细图文注释)
前端·javascript·vue.js
Mr.咕咕1 小时前
Django 搭建数据管理web——商品管理
前端·python·django