ESlint+Prettier+husky

编程规范

github代码：https://github.com/fsllala/study/tree/main/eslint_vue

Eslint+Prettier

EditorConfig、Prettier以及Eslint都用于实现前端代码规范化的工具，它们的功能分别如下：

• Eslint：代码质量检查, 编码风格约束等；
• Prettier：专注于代码格式化的工具，美化代码；
• EditorConfig：跨编辑器和IDE编写代码，保持一致的简单编码风格；

Eslint

1. 创建vite项目：npm create vite@latest；

2. 安装eslint：

   在现代开发中，推荐使用 npx eslint --init，因为它更灵活、不需要预先安装eslint ，并且是 npm/Node.js 社区的标准做法。使用 npx 可以确保使用项目本地的 ESLint 版本，避免全局版本与项目需求不匹配的问题

3. vscode需要安装插件Eslint

验证一下：这里声明一个变量但是未使用，会报错：

Tip：如果没生效，需要重启vscode（下面所有未生效情况皆是）。

4. 自定义Eslint规则

rules: {
  '规则名': '规则值'
  // eg:
  'no-console': 'error'
}

规则值：

• "off" 或 0 - 关闭规则
• "warn" 或 1 - 启用并视作警告（不影响退出）
• "error" 或 2 - 启用并视作错误（触发时退出代码为 1）

5. 通过命令查询哪里不符合规则和自动化修复
   • 查询哪里不符合规则
   • 自动化修复（修复prettier的）

// package.json 
"scripts": {
    "lint": "eslint",
    "lint:fix": "eslint --fix"
  },

配置完之后，可以通过npm run lint查询不符合规则的具体文件和位置

6. 忽略文件

   可能有的文件不需要进行校验，这里可以进行忽略的配置

   // eslint.config.js
   {
     ignores: ["node_modules/**/*", "dist/**/*"],
   },

Prettier

1. 安装依赖包：npm i prettier eslint-config-prettier eslint-plugin-prettier -D

• eslint-config-prettier

  作用：关闭所有与 Prettier 冲突的 ESLint 规则

  • 目的：防止 ESLint 和 Prettier 的格式化规则互相冲突
  • 功能：禁用 ESLint 中那些会与 Prettier 产生矛盾的格式化规则（如缩进、引号、分号等）
  • 类型：这是一个 ESLint 配置（config）
  • 使用场景：当你想让 Prettier 处理代码格式化；当你想避免 Prettier 和 ESLint 的规则冲突

  配置示例：

  {
    "extends": [
      "eslint:recommended",
      "prettier"  // 必须放在最后，覆盖其他配置
    ]
  }

• eslint-plugin-prettier

  作用：将 Prettier 作为 ESLint 规则运行

  • 目的：在 ESLint 检查时同时运行 Prettier
  • 功能：把 Prettier 的格式化问题显示为 ESLint 错误/警告 (允许通过 eslint --fix 自动修复格式问题)
  • 类型：这是一个 ESLint 插件（plugin）
  • 使用场景：当你希望 Prettier 的格式化问题作为 ESLint 错误显示；当你想要通过 ESLint 的修复功能自动修复 Prettier 的格式问题

  配置示例：

  {
    "plugins": ["prettier"],
    "rules": {
      "prettier/prettier": "error"  // Prettier 问题显示为错误
    }
  }

• 两者区别对比

特性	eslint-config-prettier	eslint-plugin-prettier
作用	关闭冲突规则	运行 Prettier 检查
类型	Config（配置）	Plugin（插件）
配置位置	extends	plugins + rules
自动修复	不支持	支持通过 eslint --fix 修复
必要性	必须	可选（推荐）

• 推荐配置

最佳实践是同时使用两者：

{
  "extends": [
    "eslint:recommended",
    "plugin:prettier/recommended"  // 简化配置，包含下面三项
  ]
}

plugin:prettier/recommended 等同于：

{
  "extends": ["prettier"],           // eslint-config-prettier
  "plugins": ["prettier"],           // eslint-plugin-prettier
  "rules": {
    "prettier/prettier": "error"     // 启用规则
  }
}

2. 在根目录下创建文件prettier.config.js

export default {
  "semi": false,              // 不加分号
  "singleQuote": true,        // 使用单引号
  "printWidth": 100,          // 每行最大字符数
  "tabWidth": 2,              // 缩进空格数
  "trailingComma": "all",     // 多行时尽可能添加尾随逗号
  "bracketSpacing": true,     // 对象字面量中的括号间打印空格
  "arrowParens": "avoid",     // 箭头函数参数只有一个时是否加括号 avoid-省略，always-总是添加
  "endOfLine": "lf",          // 换行符使用 lf
  "htmlWhitespaceSensitivity": "ignore"  // HTML 空白敏感度
}

3. 添加配置到Eslint

// 关闭与 Prettier 冲突的规则
import prettierConfig from "eslint-config-prettier";
// 将 Prettier 作为 ESLint 规则运行
import pluginPrettier from "eslint-plugin-prettier";
export default defineConfig([
  // Prettier 配置
  {
    plugins: { prettier: pluginPrettier },
    rules: {
      // prettier/prettier：规则名称
      // 第一个 prettier：插件名（来自 eslint-plugin-prettier）
      // 第二个 prettier：该插件中的具体规则名
      // "error"：错误级别
      'prettier/prettier': 'error', // 当代码格式不符合 Prettier 的规范时，ESLint 会将其标记为错误（error）
    },
  },
  // 禁用与 Prettier 冲突的规则
  prettierConfig,
]);

3. vscode需要安装插件Prettier

可以试试通过npm run lint:fix一键修复Prettier中的问题；

配置ctrl+s自动修复Prettier

在 VSCode 中配置

Tip：在 VSCode 中，配置的优先级从高到低如下：

1. 工作区设置 (.vscode/settings.json)
   • 只对当前项目有效
   • 优先级最高
2. 用户设置 (settings.json)
   • 对当前用户的所有项目有效
   • 优先级中等
3. 默认设置
   • VSCode 的默认配置
   • 优先级最低

在 .vscode/settings.json 中添加如下配置（优先级最高）

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": "explicit"
  },
  "eslint.validate": ["javascript", "typescript", "vue"]
}

这个 VSCode 设置文件（.vscode/settings.json）配置了编辑器的保存和代码格式化行为，具体作用如下：

1. "editor.formatOnSave": true

   • 保存文件时自动格式化代码
   • 使用 Prettier 作为默认格式化工具

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

   • 设置默认代码格式化工具为 Prettier 的 VSCode 扩展
   • 确保所有支持的文件类型都使用 Prettier 进行格式化

3. "editor.codeActionsOnSave"

   "source.fixAll.eslint": "explicit"

   • 保存文件时自动运行 ESLint 的自动修复功能
   • 修复可自动修复的 ESLint 错误和警告
   • "explicit" 表示只修复明确标记为可自动修复的问题

4. "eslint.validate"

   "eslint.validate": ["javascript", "typescript", "vue"]

   • 指定 ESLint 验证的文件类型
   • 包括：.js、.ts 和 .vue 文件

使用效果：保存文件时：

• 自动格式化代码（Prettier）
• 自动修复 ESLint 可修复的问题
• 保持代码风格一致

Git规范

对于git提交规范来说，不同的团队可能会有不同的标准，这里以目前使用较多的Angular团队规范延伸出的ConventionalCommitsSpecification（约定式提交）为例进行git提交规范。

约定式提交规范是一种基于提交信息的轻量级约定。 它提供了一组简单规则来创建清晰的提交历史；提交说明的结构如下所示：

原文：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

译文：

<类型>[可选 范围]: <描述>

[可选 正文]

[可选 脚注]

demo：

docs[登录授权]：修改了登录授权的文档
将文档中的公司授权改为企业授权
第188个ISSUE

Commitizen

使用 Commitizen 提交时，系统会在提交时提示您填写所有必填字段，用来规范提交的message格式；

• 仓库地址：https://github.com/commitizen/cz-cli

安装与使用

1. 安装依赖

npm install --save-dev commitizen

2. cz-customizable

   • 用于自定义提交信息的格式和选项；

   • github：https://github.com/leoforfree/cz-customizable

npm install --save-dev cz-customizable

3. 配置为插件commitizen使用cz-customizable。将这些行添加到您的package.json：

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

4. 项目根目录下创建.cz-config.cjs自定义提示文件；

   如果是ES Module规范就要用.cjs文件；如果是CommonJS 规范，就要用.js文件；

   在package.json中默认为commonjs规范，可以通过"type": "module"修改为ES Modules规范；

   • ES Modules (ESM)

     • 所有 .js 文件将被视为 ES 模块
     • 使用 import/export 语法
     • 文件扩展名使用 .js

   • CommonJS (CJS)

     • 所有 .js 文件将被视为 CommonJS 模块
     • 使用 require/module.exports 语法
     • 文件扩展名使用 .js

   • 混合使用 ESM 和 CJS

     • .mjs 文件总是作为 ES 模块
     • .cjs 文件总是作为 CommonJS 模块
     • 不受 package.json中 “type” 设置的影响

module.exports = {
  // 提交类型
  types: [
    { value: 'feat', name: 'feat:     新功能' },
    { value: 'fix', name: 'fix:      修复bug' },
    { value: 'docs', name: 'docs:     文档更新' },
    { value: 'style', name: 'style:    代码格式(不影响代码运行的变动)' },
    { value: 'refactor', name: 'refactor: 重构(既不是增加feature，也不是修复bug)' },
    { value: 'perf', name: 'perf:     性能优化' },
    { value: 'test', name: 'test:     增加测试' },
    { value: 'chore', name: 'chore:    构建过程或辅助工具的变动' },
    { value: 'revert', name: 'revert:   回退' },
    { value: 'build', name: 'build:    构建' },
  ],
  // 提交信息提示
  messages: {
    type: '请选择提交类型:',
    customScope: '请输入修改范围(可选):',
    subject: '请简要描述提交(必填):',
    body: '请输入详细描述(可选):',
    footer: '请输入要关闭的issue(可选):',
    confirmCommit: '确认使用以上信息提交？(y/n)',
  },
  // 跳过body和footer
  // skipQuestions: ['body', 'footer'],
  // 限制提交信息长度(subject文字长度默认是72)
  subjectLimit: 100,
}

5. 在package.json中添加如下脚本：就可以使用npm run commit选择了（不加这行也可以使用 npx git-cz选择）

"scripts": {
  "commit": "git-cz"
},

6. 代码提交

   这里可以先通过vsCode选择要提交的文件，然后在cli输入npm run commit进行代码提交

   

   

此时代码已经放到了本地仓库，可以通过git log进行查看：

husky + commitlint

husky + commitlint 检查提交描述是否符合Commitizen规范；

每次手动去运行命令检查太麻烦了，而且也很考验小伙伴的自觉性。husky 是一个 Git 钩子（Git hooks）工具，它可以让你在 Git 事件发生时执行脚本，进行代码格式化、测试等操作。

• 当前存在问题：虽然可以通过npm run commit对提交进行规范；但是仍然可以用git commit -m ''进行提交跳过此规范；
• 目的：当《提交描述信息》不符合约定式提交规范的时候，阻止当前的提交，并抛出对应的错误提示；
• 要完成这个目的，需要使用两个工具：
  • commitlint：用于检查提交信息；
  • husky：是一个用于 Git hooks 的工具，它能够在特定的 Git 操作（如 commit、push 等）之前或之后自动运行脚本，从而帮助开发者保持代码质量、执行代码检查、自动化任务等。讲白了，用来约束git的。

commitlint

• github：https://github.com/conventional-changelog/commitlint

1. 安装依赖

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

2. 进行规则配置

export default {
  // 继承 conventional 提交规范
  extends: ['@commitlint/config-conventional'],
  // 自定义提交类型
  rules: {
    /**
     * type-enum：类型枚举
     * 2：错误级别
     * always：总是检查
     * ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'revert', 'build']：允许的类型(和commitizen保持一致)
     */
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'docs', 'style', 'refactor', 'test', 'chore', 'revert', 'build'], // (和commitizen保持一致)
    ],
  },
}

husky

• github：https://github.com/typicode/husky
• 参考文献：https://commitlint.js.org/guides/local-setup.html

将配置好的commitlint作为规则进行使用；

1. 安装依赖

npm install --save-dev husky

2. 启动hooks，它会在 .husky/ 中创建 pre-commit 脚本，并更新 package.json 中的 prepare 脚本。随后可根据你的工作流进行修改。

npx husky init

3. 测试配置是否成功

git commit -m "Keep calm and commit"

可以看到我们提交命令被拦截了，不能被自由的正常使用git commit：

4. 将commitlint集成到husky的钩子中:
   • 删除.husky/pre-commit文件
   • 新建.husky/commit-msg文件，内容如下：

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

npx --no-install commitlint --edit $1

5. 检查集成是否成功

git commit -m "Keep calm and commit"

可以看到我们提交命令被拦截了，不能被自由的正常使用git commit，而且是按照commitlint来的

pre-commit检查提交时代码规范

刚才通过commit-msg钩子检查了提交时的commit规范；但是现在的代码层面：即使通过Eslint + Prettier进行了代码规范，但是即使不符合Eslint也是可以提交的。

我们期望通过 husky 监测pre-commit钩子，在该钩子下执行 npx eslint--ext.js,.vue src指令来去进行代码规范相关检测；

1. 新建.husky/pre-commit文件，内容如下：

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

# 检查src目录下的js和vue文件
npx eslint --ext .js,.vue src

2. 验证是否成功

修改文件，使其不符合Eslint规范，添加到暂存区进行commit：

lint-staged自动修复格式错误

• github：https://github.com/lint-staged/lint-staged

通过pre-commit处理了检测代码的提交规范问题，当我们进行代码提交时，会检测所有的代码格式规范。
但是这样会存在两个问题：


• 我们只修改了个别的文件，没有必要检测所有的文件代码格式；
• 它只能给我们提示出对应的错误，我们还需要手动的进行代码修改

1. 安装依赖

npm install --save-dev lint-staged

2. 在 package.json 文件中添加以下配置：

{
  "lint-staged": {
    // src/**/*.{js,jsx,ts,tsx} 校验暂存区、指定目录下的文件类型
    // 校验命令，执行 eslint 、prettier 
    "src/**/*.{js,jsx,ts,tsx,vue}": [
      "eslint --fix"
    ]
  }
}

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

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

npx lint-staged

4. 验证是否成功

修改文件，使其不符合Eslint规范，添加到暂存区进行npm run commit

参考文献

• eslint + vue + prettier 咋配的？
• 开启高效前端规范开发之旅！ESLint + Prettier + husky +Commitizen