代码审查和git提交引导、校验工作流

type

Post

status

Published

date

Feb 5, 2025

slug

commit

summary

prettier+eslint+lint-staged+commitlint+cz-git+husky

引言

😀

注意：本文没有过多延伸，只涉及部分注意事项，需要一定的前端基础；

文章内容仅代表个人见解，如有错漏之处欢迎指出。

此工作流主要使用如下库： prettier：代码格式化
eslint：代码检查 lint-staged：检查暂存区代码 commitlint：git commit 信息格式校验
commitizen ：cz-git 必需库 cz-git：引导式 git 提交工具
husky：Git hooks 钩子工具,用于在 Git 操作前后执行自定义脚本

一、说明

（一）项目环境及结构

1、项目环境

本示例环境如下表：

环境/工具	版本
操作系统	Windows 10
编译器	VScode 1.96.4
Node	20.16.0
项目环境	Vue3 + TypeScript

2、项目结构

项目结构如下：

3、package.json

package.json配置和依赖版本如下：

（二）工作流程

1、执行 commit 提交操作 [husky进行如下自动步骤]

2、【可选】将被修改的代码添加到暂存区

3、【自动】对暂存区进行代码格式化和检查 (检查无误进入下一步) [prettier+eslint+lint-staged]

4、【可选】进行引导式提交，对 commit 信息格式化 [commitizen+cz-git]

5、【自动】对 commit 信息的格式进行检查 (检查无误进入下一步) [commitlint]

6、代码提交到本地仓库

二、代码审查：

（一）Prettier

Prettier中文网：
什么是 Prettier？ · Prettier 中文网
Prettier 是一个有态度的代码格式化程序，支持：
https://prettier.nodejs.cn/docs/en/index.html

安装依赖

添加配置文件

配置.prettierrc.cjs文件

项目根目录下创建.prettierrc.cjs 文件，自定义prettier格式配置，prettier检查代码时会遵循以下规则。

配置.prettierignore 文件

项目根目录下创建.prettierignore 文件，自定义 prettier 忽略文件配置，prettier 检查代码时会忽略其内的文件。

在package.json中添加脚本

check:prettier 脚本仅检查项目中所有非忽略列表的文件代码格式；
lint:prettier 脚本会按照规则直接修改项目中所有非忽略列表的文件代码，使其符合规则。

脚本配置完整之后可以依次尝试是否有效。

（二）ESLint

ESLint 中文网：
ESLint 新手入门 - ESLint 中文网
插件化、可配置的 linter 工具，用于识别和报告 JavaScript 中的模式。轻松维护你的代码质量。
https://eslint.nodejs.cn/docs/latest/use/getting-started

💡

注意，本示例使用 ESLint 9，如需使用必须安装并构建 Node.js（^18.18.0、^20.9.0 或 >=21.1.0）并支持 SSL。（如果你使用的是官方 Node.js 发行版，则始终内置 SSL。）

如果你使用的是更低版本的 ESLint，请查看官网、其他教程或询问AI如何修改，因为旧版配置格式与下方示例有很大不同。因此，在使用 ESLint 9结合其他插件的配置时，请检查其他插件是否支持扁平化配置。

安装依赖

安装 ESLint

输入下面的命令进行引导式安装(如下图)，可以根据项目自定义配置。

安装其他插件

eslint-plugin-prettier用于导入 prettier 的格式化规则，转换为 ESLint 的规则，以便在 ESLint 中使用 prettier 的格式化规则，简单来说就是兼容二者使其不冲突。

添加配置文件

配置eslint.config.js文件

注意：后写的同名规则会覆盖前面的规则，故带"prettier/prettier": ["error", prettierConfig]的规则写在末尾，让 ESLint 使用 Prettier 规则进行代码格式检查，且使 Prettier 规则不被其它规则覆盖。

项目根目录下创建eslint.config.js文件，导入了js推荐配置、vue推荐配置、prettier格式配置、以及其他的 ESLint 规则（包含自定义的prettier格式配置），ESLint 检查代码时会遵循以下规则。

本示例采用的是prettier+ESLint 二者的规则进行代码格式化，ESLint 再进行代码审查。如果你用的不是prettier进行代码格式化，或不使用其他格式化工具，ESLint 也可支持代码格式化。

在package.json中添加脚本

"check": "eslint ." 脚本仅检查项目中所有非忽略列表的文件代码格式；
"lint": "eslint . --fix" 脚本会按照规则直接修改项目中所有非忽略列表的文件代码，并再次报告无法修改的格式错误。

脚本配置完整之后可以依次尝试是否有效，日常使用lint脚本进行检查并修复；

运行任意脚本后控制台报红，则表示有代码不符合格式规则或不正确，如果提醒“- - fix”且下方显示可修复，则可再次运行lint脚本进行检查并修复，否则需要手动前往该文件进行修改；

如果项目代码格式全部匹配你创建的规则，ESLint 不会输出任何成功提示信息，这点和prettier不同。

（三）lint-staged

针对暂存区需要提交的文件运行格式化程序和代码审查等任务。
仅对“暂存区”的代码进行操作，这样只会检查本次你修改的代码，而不必每次提交代码时检查并修改整个项目的代码——这会使你的团队成员无法辨别哪些是格式变动，哪些是你真正的逻辑变更。（同时防止替人背锅）
项目地址：
lint-staged
lint-staged • Updated Nov 29, 2025

安装依赖

添加配置文件

在package.json中添加脚本

lint-staged 脚本仅针对项目暂存区中的，匹配以下规则的代码执行对应的检查脚本，一般用于结合 husky 以在提交代码前自动触发，如果检查不通过会中断提交操作。（后文会介绍）
lint:diff脚本可将已修改的代码添加到暂存区，然后执行代码检查，这在团队协作中很有用；区别于lint脚本直接修改整个项目的代码。

脚本配置完整之后可以尝试"lint-staged"脚本是否有效。

上方的"lint-staged" 是lint-staged的配置项，你也可以根据不同的文件类型运行不同的脚本，也可以依次使用多个检查脚本，如下方示例：

但因为在前文的配置中 prettier 规则已经内置于 eslint 规则中，此处仅配置 eslint 的脚本即可。

三、Git检查

（一）commitlint

用于规范和检查你的提交信息格式。
commitlint官网：
Guide: Local setup | commitlint
Lint commit messages
https://commitlint.js.org/guides/local-setup.html

安装依赖

添加配置文件

配置commitlint.config.cjs文件

注意：如果你需要后文cz-git的引导性提交功能，会有另外的commitlint.config.cjs配置，可直接前往查看cz-git教程。此处示例不包括cz-git配置项；
规则没有逐一测试检查，如有错误还请反馈。

项目根目录下创建commitlint.config.cjs文件，自定义commitlint格式配置。

测试脚本

注意：因为下文才会配置 husky来在每次提交时自动运行commitlint 脚本，所以此处只能手动运行 commitlint 检查上一次的提交信息。

运行下方命令，可以检查上一次的提交信息是否符合规则。

（二）cz-git

用于引导开发者填写提交信息。
如开发者所说，我也是尝试了cz-customizable 和 git-cz 之后觉得配置过少，最后才选择了cz-git。
cz-git 官网：
cz-git - commitizen adapter and CLI
支持 OpenAI 自动生成描述，且工程性更强，轻量级，高度自定义，输出标准格式的 commitizen 适配器与 git commit 命令行工具。
https://cz-git.qbb.sh/zh/guide/

安装依赖

安装commitizen

cz-git需要全局安装commitizen来运行。

安装cz-git

cz-git可以全局安装也可以项目内安装，可以查看官网。

全局安装可以在所有项目中使用，项目被安装仅在当前项目中生效。

本示例采用项目内安装。

添加配置文件

cz-git也有多种配置方式，单独文件配置或与提交检查工具的组合配置，详见官网。

本示例采用与commitlint的组合配置。

配置commitlint.config.cjs文件

注意：此处示例包括cz-git配置项和commitlint配置项，其中cz-git的配置项都在prompt中，其余部分都是commitlint配置项；
外部的scope本地缓存设置若不需要可删除相关代码；
规则没有每一项都测试检查，如有错误还请反馈。

项目根目录下创建commitlint.config.cjs文件，自定义commitlint格式配置和cz-git配置项，以及cz-git的scope本地缓存设置项。

在package.json中添加脚本

注意：因为下文才会配置 husky来在每次提交时自动运行commitlint 脚本，所以此处只能测试cz-git是否正常工作，无法测试 commitlint 检查。

注意config与scripts同级。

（1）修改项目内任意文件，并运行命令git add .将文件提交到暂存区之后；

（2）运行命令cz或git cz会触发git commit提交操作；

（3）如果cz-git工作正常，会显示commitlint.config.cjs的prompt的messages信息，如下图。

（4）按Ctrl键+C键即可退出。

四、工作流合并

husky

用于在git commit前后执行自定义脚本的工具.
注意本示例使用的 husky 9，旧版本的配置与本示例不相同。
husky 官网：
Husky
使 Git hooks 变得简单
https://typicode.github.io/husky/zh/

安装依赖

安装 husky

初始化husky

此命令会在package.json中创建prepare脚本，在项目根目录下创建.husky文件夹，其中有_文件夹和pre-commit文件。

prepare脚本会在您npm install后自动安装Husky的钩子，用于给项目其他成员拉取代码后自动初始化husky。

_文件夹中是husky的自带脚本，其文件命名代表git的Hooks的生命周期。开发者可遵照其中命名，在_文件夹同级的创建同名配置文件，在其中自定义需要运行的脚本。

例如pre-commit文件指在提交信息(引导)完成之后，提交代码到本地仓库之前执行。

husky的配置文件会按git的Hooks生命周期依次执行，其中的脚本按先后顺序执行。

添加配置文件

添加提交信息格式检查hook

在此目录下新建commit-msg文件，在其中添加如下脚本。

这将在你填写完提交信息之后自动对提交信息进行格式检查。

添加代码格式检查hook【未配置cz-git】

💡

如果你没有配置cz-git ，进行如下配置

（1）删除pre-commit文件中的默认脚本pnpm test，添加下面的脚本；

这将在提交信息(引导)完成之后，提交代码到本地仓库之前执行之前，所有被修改的代码会添加到暂存区，然后运行配置的脚本lint-staged进行代码检查

（2）在package.json中添加commit脚本。

每次执行时会先将被修改的代码添加到暂存区，然后进行提交操作。

此时会触发husky的pre-commit，运行配置的脚本lint-staged对暂存区代码进行检查，检查有误可运行lint:diff脚本执行自动修复或手动修复，检查无误才能输入commit信息。

commit信息输入完成之后会触发husky的commit-msg对其进行格式检查，然后commitlint检查无误才会将代码提交到本地仓库。

添加代码格式检查hook【配置了cz-git】

💡

如果你配置了cz-git，推荐进行如下配置。

因为cz-git的执行时机比pre-commit更早，按上面的配置来，在引导提交信息之后，如果代码格式检查有问题，就需要修改代码之后重新填写commit信息，然后再次检查。

当然，你也可以手动运行lint脚本先检查再提交

(1)用#注释pre-commit中的脚本，或直接删除pre-commit；

(2)在package.json中添加commit脚本。

每次执行时会先将被修改的代码添加到暂存区，然后运行配置的脚本lint-staged进行代码检查，检查有误可运行lint:diff脚本执行自动修复或手动修复，检查无误才会执行cz进行引导式提交。

commit信息输入完成之后会触发husky的commit-msg对其进行格式检查，然后commitlint检查无误才会将代码提交到本地仓库。