本文面向React 19 Vite的前端工程化场景目标是让团队在每次提交时自动完成代码格式化Prettier 统一代码风格代码质量修复ESLint 在提交前对暂存文件自动--fix提交说明规范Commitlint 校验提交信息Conventional Commits本方案使用simple-git-hooks把钩子脚本写入仓库的.git/hooks/lint-staged只对暂存区文件运行 ESLint/Prettier避免全量扫描commitlint在commit-msg钩子校验提交说明可选Commitizen cz-git交互式生成符合规范的提交说明如果你只想了解“当前仓库里这些配置如何协作/如何排查”请看frontend/docs/git-hooks.md。流程图提交流程或直接 git commit -m否是否是git addgit commitgcInpre-commit 钩子lint-stagedeslint / prettier通过?提交中断commit-msg 钩子commitlint说明合规?提交中断提交成功安装与生成钩子pnpm installprepare 生命周期simple-git-hooks写入 .git/hooks图例简要commitlint/config-conventional为 Commitlint 提供默认规则集commitizen提供git-cz入口交互由cz-git完成。先完成左侧“安装并生成.git/hooks”右侧提交流程才会在每次git commit时自动执行。前置条件仓库已初始化 Git存在.git/。在包含前端package.json的目录执行安装与脚本本仓库为frontend/。已安装pnpm下文以 pnpm 为例如团队使用 npm/yarn可自行等价替换。步骤 1安装开发依赖在目标目录例如frontend/执行pnpmadd-Dsimple-git-hooks lint-staged commitlint/cli commitlint/config-conventional上述依赖分工如下包名作用simple-git-hooks根据package.json的simple-git-hooks配置把要执行的命令写入仓库.git/hooks/如pre-commit、commit-msg配合prepare让协作者安装依赖后自动同步钩子。lint-staged仅对Git 暂存区文件按 glob 运行命令如 eslint、prettier通常挂在pre-commit钩子里避免全仓库扫描、加快提交前检查。commitlint/cli提供commitlint命令行在commit-msg钩子里读取本次提交说明并按规则校验不通过则提交失败。commitlint/config-conventionalCommitlint 的预设规则包对应常见 Conventional Commits如feat、fix等类型前缀在.commitlintrc.js中通过extends引用。提交前“格式化 修复”还需要ESLint、Prettier。本仓库已在frontend里完成配置如果你在其他项目从零搭建请先把这两者安装并配置好。可选交互式写提交说明与本仓库一致pnpmadd-Dcommitizen cz-git包名作用commitizen提供git-cz通常映射为pnpm run commit的交互式提交流程入口。cz-gitCommitizen 的适配器可在.commitlintrc.js中统一配置中文提示、类型列表并与 commitlint 规则对齐。步骤 2添加prepare脚本在package.json的scripts中加入prepare是 npm 生命周期脚本名用于“安装依赖后自动执行”prepare:simple-git-hooks步骤 3声明simple-git-hooks钩子命令在package.json根级增加与scripts平级的字段例如与本项目一致“pre-commit”: 在提交代码之前执行 lint-staged对暂存的文件运行 ESLint 和 Prettier 修复/格式化“commit-msg”: 在提交信息被保存时执行 commitlint依据 .commitlintrc.js 配置校验提交说明规范$1 表示提交信息文件路径simple-git-hooks:{pre-commit:npx lint-staged,commit-msg:npx commitlint --config .commitlintrc.js --edit $1}说明pre-commit提交前执行lint-staged见步骤 5。commit-msg提交时校验说明$1为 Git 传入的提交信息文件路径。若在个别 Windows shell 下异常优先参考 simple-git-hooks / commitlint 的 Windows 说明或统一在 Git Bash / WSL 环境执行。按需可增加其他钩子如pre-push键名与 Git 钩子文件名对应。步骤 4配置 Prettier用于代码格式化若项目尚未安装 Prettierpnpmadd-Dprettier创建.prettierrc示例与本仓库一致singleQuote: 是否使用单引号。false 表示用双引号。trailingComma: 末尾逗号策略。all 表示对象/数组等都加尾逗号。printWidth: 每行最大字符数。超过会自动换行常用 80。tabWidth: 缩进空格数2 代表每级缩进2个空格。semi: 语句末是否添加分号。true 表示结尾加分号。{singleQuote:false,trailingComma:all,printWidth:80,tabWidth:2,semi:true}创建.prettierignore示例与本仓库一致node_modules/ dist/说明本仓库已包含frontend/.prettierrc与frontend/.prettierignore你通常不需要重复创建这里用于“从零搭建”时对齐配置。步骤 5配置lint-staged提交前只处理暂存文件在package.json根级增加lint-staged字段按文件类型声明命令。与本项目一致时可采用JS/TS/HTML 文件先通过 eslint 自动修复再用 prettier 格式化样式文件仅用 prettier 格式化Markdown、JSON、YAML仅用 prettier 格式化lint-staged:{*.{js,jsx,ts,tsx,html}:[eslint --fix,prettier --write],*.{css,scss,less}:[prettier --write],*.{md,json,yml,yaml}:[prettier --write]}可按技术栈增删 glob 或命令例如仅 Prettier、或增加stylelint。步骤 6添加 Commitlint 配置在package.json同级新建.commitlintrc.js或.commitlintrc.cjs等需与步骤 3 中--config路径一致。最小可用示例继承 Conventional Commitsexportdefault{extends:[commitlint/config-conventional],};常用规则样例可直接复制后按团队规范调整exportdefault{extends:[commitlint/config-conventional],rules:{// 允许的提交类型与 Conventional Commits / cz-git 常用类型对齐type-enum:[2,always,[feat,fix,docs,style,refactor,perf,test,build,ci,chore,revert,],],// header 总长度限制如feat(login): add remember meheader-max-length:[2,always,100],// scope 规则可选如果你们要求必须写 scope把 0 改成 2scope-empty:[0,never],// subject 规则不允许句号结尾且至少有内容subject-empty:[2,never],subject-full-stop:[2,never,.],// subject 大小写多数团队会放宽允许中文/任意大小写subject-case:[0,never],},};本仓库在此基础上使用了 cz-git 的defineConfig、自定义rules与中文prompt可直接参考frontend/.commitlintrc.js按需裁剪。步骤 7可选Commitizen cz-git在package.json中增加scripts:{commit:git-cz},config:{commitizen:{path:node_modules/cz-git}}日常执行pnpm run commit按向导填写类型与描述减少手写格式错误。步骤 8生成钩子文件任选其一推荐执行依赖安装会触发preparepnpminstall或手动执行npx simple-git-hooks完成后仓库.git/hooks/下应出现或更新pre-commit、commit-msg等脚本。步骤 9自测验证会自动格式化/修复修改若干文件并git add。执行git commit或pnpm run commit确认pre-commit会运行 lint-staged可能会自动改动文件并要求你重新git add。commit-msg会校验提交说明故意写不符合规范的 message 时应失败。修改配置后如何让钩子更新若更新了simple-git-hooks或lint-staged等字段请重新执行pnpm install或npx simple-git-hooks使.git/hooks与最新配置一致。