前端代码规范一站式配置教程

木子M
150 阅读11分钟

前言

在团队协作开发中，由于每位成员的编码习惯和风格各异，项目的代码风格可能会显得参差不齐。随着项目规模的增长和团队协作的深化，保持代码的一致性和可读性变得愈发重要。一个统一且良好的前端代码规范不仅能够显著提升代码质量，还能增强团队的协作效率，降低新成员的上手难度，并有效减少潜在的代码错误。

在接下来的讨论中，我们将深入探讨前端工程化中的一些关键工具，包括 ESLint、Prettier、Husky 以及 Lint-staged 。我们将详细介绍这些工具的安装、配置和使用方式，展示如何利用它们来实现代码规范，从而提升项目的整体质量和团队的工作效率。

使用ESLint

官网及介绍

ESLint官网地址：eslint.org/

ESLint中文网地址：eslint.nodejs.cn/

ESLint 是一个可配置的 JavaScript linter。它可以帮助你发现并修复 JavaScript 代码中的问题。问题可以是任何事情，从潜在的运行时错误到不遵循最佳实践，再到样式问题。

简单来说ESLint功能就是

  1. 对JS语法检测、限制和修复（例如检测未定义变量、未使用的变量等）
  2. 对代码风格进行格式化（不能对css、less等格式化）
  3. 支持插件（可扩展支持 React、Vue 等框架的特定规则）

安装及配置

npm install eslint

配置eslint，可采用两种方案，第一种是手动创建文件进行配置，另一种是运行初始化命令根据提示来选择配置。

先说第一种手动配置eslint文件： 在根目录下创建eslint.config.js文件，并进行基础的简单配置(演示中所安装的ESLint版本为9.17 旧配置文件弃用也就是原有的.eslintrc以及.eslintignore等配置文件弃用)，例如：

export default [
  {
      rules: {
          semi: "error",
          "prefer-const": "error"
      }
  }
];

注⚠️：ESLint 配置文件可以命名为以下任意名称

  • eslint.config.js
  • eslint.config.mjs
  • eslint.config.cjs

然后是第二种运行初始化命令：

npx eslint --init

选择配置：

eslint-init.jpg

初始化后的文件：

import globals from "globals"; // 导入了 ‘globals’全局变量的库模块，该模块提供了一组预定义的全局变量（如 window、document 等），这些变量通常在不同的环境（如浏览器、Node.js）中可用。在 ESLint 配置中，可以使用该模块来指定代码所运行的环境，从而定义全局变量。

import pluginVue from "eslint-plugin-vue"; // 导入‘eslint-plugin-vue’插件，该插件提供了 Vue.js 特有ESLint规则。确保Vue文件（`.vue` 文件）中的代码符合Vue.js的最佳实践和代码风格指南


/** @type {import('eslint').Linter.Config[]} */
export default [
  {files: ["**/*.{js,mjs,cjs,vue}"]}, // 文件匹配：‘files’属性指定了哪些文件类型（JavaScript、TypeScript、Vue 文件等）将应用这些规则
  
  {languageOptions: { globals: globals.browser }}, // 全局变量：‘languageOptions’配置了浏览器环境下的全局变量。
  
  ...pluginVue.configs["flat/essential"], // 引入‘eslint-plugin-vue’插件的基础规则
];

我们可以往其中添加自己想要的代码规范规则，例如：

export default [
    ....
    {
    rules: {
      // 所有文件引号规则为单引号
      quotes: ['error', 'single'],
      // 禁止使用console
      'no-console': 'off',
      // 禁止使用debugger
      'no-debugger': 'off',
    },
  },
]

VSCode中关于ESLint的相应扩展

eslint.png 安装这个扩展插件后，项目中哪些代码触发了ESLint报错的规则，就实时给我们展示出来，我们可以根据提示进行相应的修改

如果希望ESLint还能帮我们自动修复代码，那么我们还可以执行他的--fix命令

eslint --fix

Prettier

官网及介绍

官网地址：prettier.io/

Prettier 是一个专注于代码格式化的工具，可以对多种代码，包括js、jsx、ts、json、css、less、scss、html、vue等进行格式化，自动调整代码风格，使代码保持一致性和可读性。 Prettier不可以对任何语法检测、限制和修复

安装及配置

安装

我们有两种方式，一种是install安装依赖，然后编写配置文件

npm install prettier

另一种是直接在VSCode中安装Prettier扩展，然后编写配置文件

prettier.png

配置

编写prettier.config.js配置文件

module.exports = {
  semi: false, // true（默认）: 在每条语句的末尾添加一个分号。false：仅在可能导致 ASI 失败的行的开头添加分号。
  singleQuote: true, // 使用单引号而不是双引号
  trailingComma: 'none', // "none":没有尾随逗号。"es5": 在 ES5 中有效的尾随逗号（对象、数组等），TypeScript 中的类型参数中没有尾随逗号。"all"- 尽可能使用尾随逗号。
};

然后设置VSCode保存时自动格式化代码，这时候我们保存代码就会按照编写的Prettier规范来自动格式化了。注意如果我们安装了多个格式化工具那么要选择Prettier为默认的代码格式化工具。如果还是没有按照自己编写的起作用那么我们需要看一下settings.json是不是设置了某个文件的默认格式化工具

如果我们没有设置自动格式化也可以配置脚本帮我们执行的：

"scripts": { 
    "prettier": "prettier --write ."
 }

当我们执行npm run prettier 时就会一次性全部格式化了。

我们还可以格式化特定文件夹/文件：

npx prettier --write src/ 
npx prettier --write src/App.vue

Prettier和ESlint有什么区别

很多对代码规范不熟悉的小伙伴可能会困惑，这两者都是代码格式化的工具，那这两者到底有什么区别呢？我只用其中一种可不可以呢？

首先Prettier更专注于代码的外观，例如换行位置对不对，是单引号还是双引号....它是让代码看起来整齐一致，易于阅读，美化代码格式的，不会去管代码逻辑对不对。ESLint专注于代码的语法和逻辑规范，例如定义了变量却没有使用....它是检查代码质量的。Prettier 就像是“美工”，专门帮你整理房间，让家具摆放整齐、颜色协调，看着舒服。ESLint 就像是“安全检查员”，检查电线是否漏电、门窗是否锁好，确保不会出问题。

功能用途都不一样我们当然可以择一选用了，但是我们更推荐结合使用，用ESLint来检测语法，Prettier调整风。格下面我们说下两者应该如何使用

ESLint和Prettier结合使用

eslint-plugin-prettier

另外如果ESLint和Prettier发生冲突，我们可以安装eslint-plugin-prettier插件

npm install eslint-plugin-prettier --save-dev

然后将Prettier集成到ESLint中。

import globals from 'globals';
import pluginVue from 'eslint-plugin-vue';

/** @type {import('eslint').Linter.Config[]} */
export default [
  { files: ['**/*.{js,mjs,cjs,vue}'] },
  { languageOptions: { globals: globals.browser } },
  ...pluginVue.configs['flat/essential'],
  {
    plugins: {
        prettier: true,
    },
    rules: {
        "prettier/prettier": "warn",
        // 所有文件引号规则为单引号
        quotes: ['error', 'single'],
        // 禁止使用console
        'no-console': 'off',
        // 禁止使用debugger
        'no-debugger': 'off',
    }
  },
];

如果不想安装集成到话也可以根据报错提示或者官网配置来重写ESLint规范

Commitizen

当我们编写完成代码要提交代码当仓库时是要输入描述信息的，但是不同人写的描述信息都是按照自己理解来的，这就导致看提交记录时候云里雾里不知道到底完成了哪些修复了哪些，所以我们需要有个约定代码提交规范。

Commitizen 是一个用于规范化 Git 提交信息的工具，帮助开发者按照特定的格式（如 Conventional Commits）编写提交消息，确保提交记录清晰规范

首先我们对其进行安装

npm install commitizen -D

配置 Commitizen

Commitizen 需要一个适配器（adapter）来定义提交消息的规范。在此我们用两个适配器举例，分别是cz-customizable和cz-conventional-changelog

cz-customizable

对应npm地址：www.npmjs.com/package/cz-…

首先安装

npm i cz-customizable

然后将以下配置添加到package.json中：

...
"config": {
  "commitizen": {
    "path": "node_modules/cz-customizable"
  }
}

config.commitizen.path 是用于指定生成提交消息的适配器的路径

根项目下创建.cz-config.js自定义提示文件

module.exports = {
  // type 类型（定义之后，可通过上下键选择）
  types: [
    { value: 'feat', name: 'feat:     新增功能' },
    { value: 'fix', name: 'fix:      修复 bug' },
    { value: 'docs', name: 'docs:     文档变更' },
    { value: 'style', name: 'style:    代码格式（不影响功能，例如空格、分号等格式修正）' },
    { value: 'refactor', name: 'refactor: 代码重构（不包括 bug 修复、功能新增）' },
    { value: 'perf', name: 'perf:     性能优化' },
    { value: 'test', name: 'test:     添加、修改测试用例' },
    { value: 'build', name: 'build:    构建流程、外部依赖变更（如升级 npm 包、修改 webpack 配置等）' },
    { value: 'ci', name: 'ci:       修改 CI 配置、脚本' },
    { value: 'chore', name: 'chore:    对构建过程或辅助工具和库的更改（不影响源文件、测试用例）' },
    { value: 'revert', name: 'revert:   回滚 commit' }
  ],
  // 交互提示信息
  messages: {
    type: '确保本次提交遵循 Angular 规范！\n选择你要提交的类型：',
    scope: '\n选择一个 scope（可选）：',
    // 选择 scope: custom 时会出下面的提示
    customScope: '请输入自定义的 scope：',
    subject: '填写简短精炼的变更描述：\n',
    body:
      '填写更加详细的变更描述（可选）。使用 "|" 换行：\n',
    breaking: '列举非兼容性重大的变更（可选）：\n',
    footer: '列举出所有变更的 ISSUES CLOSED（可选）。 例如: #31, #34：\n',
    confirmCommit: '确认提交？'
  },
 
  // 设置只有 type 选择了 feat 或 fix，才询问 breaking message
  allowBreakingChanges: ['feat', 'fix'],
 
  // 跳过要询问的步骤
  // skipQuestions: ['body', 'footer'],
 
  // subject 限制长度
  subjectLimit: 100
}

当我们要提交代码时使用git cz来代替git commit，即可看到提示内容

cz-conventional-changelog

初始化cz-conventional-changelog

npx commitizen init cz-conventional-changelog --save-dev --save-exact

然后再提交代码使用npx cz 即可（在此之前还是需要git add）

如果我们想要根据项目需求自定义某些配置，可以在package.json 中的 config.commitizen 里面进行相应的修改

虽然我们这么配置了，但是是对按这种方式提交做的规范，仍然无法避免通过commit提交不规范代码，所以我们要对commit的提交进行规范限制。

使用Husky + Commitlint检查提交描述是否符合规范要求

我们在上面说到如果依旧使用commit来提交我们现在是没有办法对限制的，我们希望当提交的描述信息不符合约定式提交规范的时候，阻止当前的提交，并抛出对应的错误提示。

要实现这个需求，我们需要先了解什么叫Git hooks。这是git的钩子函数，简单来说就是合适的时间要做合适的事。我们所期望的阻止不合规的提交信息，就需要用到其中的pre-commit和commit-msg

pre-commit：在git commit执行前调用，常用于检查代码质量（如 linting、格式化）等，若检查失败则阻止提交

commit-msg：在提交消息创建后触发，主要用于验证提交消息格式等内容，若不符合规则，则阻止提交。

简单来说commit-msg是检验提交信息也就是commit -m中的描述，pre-commit是检验内容,也就是commit的代码。然后我们开始就要用到git hooks来校验我们的提交信息。

ok明确了这个之后我们就要来具体实现上面所说的需求，我们需要用到两个工具：

  1. Commitlint 用于检查提交信息
  2. Husky 用于在 Git 项目的工作流中集成 Git Hooks

Commitlint

首先对其进行安装

npm install @commitlint/config-conventional @commitlint/cli -D

在项目的根目录创建commitlint.config.js文件，用于配置commitlint校验规则

module.exports = {
  extends: ["@commitlint/config-conventional"], // 继承'@commitlint/config-conventional'规则集中的所有规则来验证提交消息，也就是我们采用的是cz-conventional-changelog的提交规则
};

如果想要进行一些自定义的话直接在rules对象中添加即可，另外如果你使用的是cz-customizable然后自定义的提示文件那么在这也是需要添加的，例如：

module.exports = {
  extends: ["@commitlint/config-conventional"], // 继承'@commitlint/config-conventional'规则集中的所有规则来验证提交消息
  
  rules: {
      "type-enum": [
          2, // 当前验证错误级别
          "always", // 在什么情况下进行验证
          // 泛型内容
          [
              "feat",
              "fix",
              "docs",
              "style",
              // ....
          ]
      ]
  };

这样我们就配置好了检查提交的工具，但是什么时候去检查呢？下面就要用到Husky

Husky

执行以下命令

npx husky-init && npm install

这是个组合命令，会帮我们安装Husky，配置prepare脚本初始化.husky文件夹并启用Husky，还会创建一个默认钩子。

再通过以下指令生成.husky/commit-msg 文件，验证提交信息

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

此时我们再随意git commit -m 'xxxxxx'输入不符合规范的信息是不会再提交成功的，会报错 提交不合规，这样我们就做好了git消息提交规范。

但是代码格式提交规范还没有做。有人可能有疑问我们不是做过了吗？前面我们都已经通过ESLint和Prettier配合解决了代码格式问题，但是我们的这个操作只可以解决本地的代码格式问题，我们需要配置自动保存格式化或者执行格式化命令才可以，如果有人没有执行代码格式化的操作直接就提交了，代码就会变得凌乱，我们希望如果出现这种情况，我们提交代码，如果符合规则就提交成功，如果不符合自动执行eslint --fix尝试帮助自动修复。修复成功则会帮助我们把修复好的代码进行提交，修复失败则会提示错误，我们只有修好这个错误后才能被允许提交代码。

安装lint-staged:

npm install lint-staged -D

修改.husky/pre-commit文件内容：

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npx lint-staged

修改package.json配置：

"lint-staged": {
    "src/**/*.{js,vue}": [
      "eslint --fix",
      "prettier --write",
      "git add"
    ]
  }

注： lint-staged 允许你只对 Git 暂存区的文件运行命令，这样可以提高效率，避免对所有文件进行检查。也有人用lint，它通常用于全局检查整个项目的代码，个人根据需求来定即可。如果你想使用使用lint， 修改.husky/pre-commit文件内容：

#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

npm run prepare-commit

在package.json文件script中添加脚本：

"lint": "eslint . --fix", 
"format": "prettier --write .", 
"lint-and-format": "npm run lint && npm run format", 
"prepare-commit": "npm run lint-and-format && git add"

好了，完结，撒花🎉

avatar
文章
阅读
粉丝