前端Husky配置规范书

前端Husky配置规范书一、Husky简介与核心价值Husky是一款为Git仓库提供GitHooks管理的工具，它允许开发者在Git执行特定命令（如commit、push等）时，自动触发自定义脚本，从而实现代码质量校验、提交信息规范检查等自动化工作流。在前端项目中，Husky的核心价值主要体现在以下几个方面：1.代码质量保障通过在commit或push阶段触发ESLint、Prettier等代码检查工具，Husky可以在代码提交前自动检测代码中的语法错误、格式问题以及不符合团队规范的代码风格，避免低质量代码进入版本库。例如，当开发者执行gitcommit命令时，Husky会自动运行ESLint检查，如果发现代码中存在未定义变量、语法错误等问题，会阻止提交并提示具体错误信息，确保只有通过检查的代码才能被提交。2.提交信息规范化借助commitlint工具，Husky可以强制开发者按照统一的提交信息规范编写提交说明，如Angular团队的提交信息规范。规范化的提交信息不仅便于团队成员理解代码变更的内容和目的，还能自动生成CHANGELOG文档，提高项目的可维护性和协作效率。例如，提交信息必须遵循type(scope):subject的格式，其中type表示提交的类型（如feat表示新功能、fix表示修复bug等），scope表示影响的范围，subject是对提交内容的简短描述。3.自动化工作流集成Husky可以与其他前端工具和服务集成，实现自动化的工作流。例如，在push代码前自动运行单元测试、集成测试，确保代码变更不会破坏现有功能；或者在提交代码后自动触发CI/CD流程，进行代码构建、部署等操作。通过这种方式，Husky可以减少手动操作，提高开发效率，同时降低人为错误的风险。二、Husky安装与基础配置1.环境准备在开始配置Husky之前，需要确保项目满足以下环境要求：Node.js版本：建议使用Node.js14及以上版本，因为Husky7+版本对Node.js的版本有一定要求。可以通过node-v命令检查当前Node.js版本。Git仓库：项目必须是一个Git仓库，如果还没有初始化Git仓库，可以通过gitinit命令进行初始化。2.安装Husky可以通过npm或yarn来安装Husky，以下是两种安装方式的具体步骤：使用npm安装#安装Husky到项目开发依赖npminstallhusky--save-dev#启用GitHooksnpxhuskyinstall使用yarn安装#安装Husky到项目开发依赖yarnaddhusky--dev#启用GitHooksyarnhuskyinstall安装完成后，Husky会在项目根目录下创建一个.husky文件夹，用于存放GitHooks脚本。3.配置package.json脚本为了方便后续启用Husky，可以在package.json文件中添加一个prepare脚本，这样在项目依赖安装完成后会自动启用Husky。修改package.json文件如下：{"scripts":{"prepare":"huskyinstall"}}添加完成后，当其他团队成员克隆项目并执行npminstall或yarninstall命令时，Husky会自动启用，无需手动执行huskyinstall命令。三、GitHooks配置与常用场景1.常用GitHooks介绍Git提供了多种Hooks，用于在Git命令执行的不同阶段触发自定义脚本。在前端项目中，常用的GitHooks主要包括以下几个：pre-commit在执行gitcommit命令后、提交信息被写入之前触发。通常用于在代码提交前进行代码质量检查、格式化等操作，确保提交的代码符合团队规范。commit-msg在提交信息被编辑完成后、提交完成之前触发。主要用于检查提交信息是否符合规范，如果不符合规范，会阻止提交并提示错误信息。pre-push在执行gitpush命令后、代码被推送到远程仓库之前触发。可以用于在推送代码前运行测试、构建等操作，确保代码可以正常构建和运行，避免将有问题的代码推送到远程仓库。2.配置pre-commitHookpre-commitHook主要用于在代码提交前进行代码质量检查和格式化。以下是配置pre-commitHook的具体步骤：步骤1：添加pre-commitHook使用Husky命令添加pre-commitHook：npxhuskyadd.husky/pre-commit"npmrunlint"上述命令会在.husky文件夹下创建一个pre-commit脚本文件，并在其中添加npmrunlint命令。这里的lint是在package.json中定义的脚本命令，用于运行ESLint检查代码。步骤2：配置ESLint如果项目中还没有安装ESLint，可以通过以下命令进行安装：npminstalleslint--save-dev安装完成后，初始化ESLint配置：npxeslint--init根据提示选择相应的配置选项，如代码风格、使用的框架等。初始化完成后，会在项目根目录下生成一个.eslintrc.js或.eslintrc.json配置文件，用于配置ESLint的检查规则。在package.json中添加lint脚本：{"scripts":{"lint":"eslint.--ext.js,.jsx,.ts,.tsx"}}上述脚本会检查项目中所有.js、.jsx、.ts和.tsx文件是否符合ESLint规则。步骤3：配置Prettier（可选）如果团队使用Prettier进行代码格式化，可以将Prettier与ESLint集成，在pre-commit阶段自动格式化代码。首先安装Prettier和相关插件：npminstallprettiereslint-config-prettiereslint-plugin-prettier--save-dev然后修改ESLint配置文件，将Prettier集成到ESLint中：module.exports={extends:['eslint:recommended','plugin:prettier/recommended'],plugins:['prettier'],rules:{'prettier/prettier':'error'}};在package.json中添加format脚本，用于自动格式化代码：{"scripts":{"format":"prettier--write."}}修改pre-commitHook脚本，在执行ESLint检查前先自动格式化代码：npxhuskyadd.husky/pre-commit"npmrunformat&&npmrunlint"这样，当开发者执行gitcommit命令时，Husky会先运行npmrunformat自动格式化代码，然后运行npmrunlint检查代码，如果发现问题会阻止提交并提示错误信息。3.配置commit-msgHookcommit-msgHook用于检查提交信息是否符合规范。以下是配置commit-msgHook的具体步骤：步骤1：安装commitlint安装commitlint及其相关依赖：npminstall@commitlint/cli@commitlint/config-conventional--save-dev其中，@commitlint/cli是commitlint的命令行工具，@commitlint/config-conventional是遵循Angular团队提交信息规范的配置文件。步骤2：配置commitlint在项目根目录下创建一个commitlint.config.js文件，配置commitlint使用的规范：module.exports={extends:['@commitlint/config-conventional']};上述配置表示commitlint将使用Angular团队的提交信息规范。如果团队有自定义的提交信息规范，可以在此文件中进行配置。步骤3：添加commit-msgHook使用Husky命令添加commit-msgHook：npxhuskyadd.husky/commit-msg"npx--no--commitlint--edit$1"上述命令会在.husky文件夹下创建一个commit-msg脚本文件，并在其中添加npx--no--commitlint--edit$1命令。该命令会在提交信息编辑完成后，调用commitlint检查提交信息是否符合规范，如果不符合规范，会阻止提交并提示具体错误信息。4.配置pre-pushHookpre-pushHook用于在代码推送到远程仓库前进行一些检查和操作，如运行测试、构建等。以下是配置pre-pushHook的具体步骤：步骤1：添加pre-pushHook使用Husky命令添加pre-pushHook：npxhuskyadd.husky/pre-push"npmruntest"上述命令会在.husky文件夹下创建一个pre-push脚本文件，并在其中添加npmruntest命令。这里的test是在package.json中定义的脚本命令，用于运行项目的单元测试。步骤2：配置单元测试如果项目中还没有配置单元测试，可以选择合适的测试框架，如Jest、Mocha等，并进行安装和配置。以Jest为例，安装Jest：npminstalljest--save-dev在package.json中添加test脚本：{"scripts":{"test":"jest"}}编写单元测试用例，确保测试可以正常运行。当开发者执行gitpush命令时，Husky会自动运行npmruntest命令，如果测试失败，会阻止代码推送到远程仓库，确保只有通过测试的代码才能被推送。四、Husky与其他工具集成1.与Lint-staged集成Lint-staged是一个用于在Git暂存文件上运行linters的工具，它可以只对本次提交的文件进行代码检查和格式化，而不是对整个项目的文件进行检查，从而提高检查效率。以下是Husky与Lint-staged集成的具体步骤：步骤1：安装Lint-stagednpminstalllint-staged--save-dev步骤2：配置Lint-staged在项目根目录下创建一个.lintstagedrc文件，配置Lint-staged需要执行的命令：{"*.{js,jsx,ts,tsx}":["eslint--fix","prettier--write"],"*.{html,css,scss,less}":["prettier--write"]}上述配置表示，对于.js、.jsx、.ts、.tsx文件，先运行ESLint的自动修复命令，然后运行Prettier进行格式化；对于.html、.css、.scss、.less文件，直接运行Prettier进行格式化。步骤3：修改pre-commitHook修改pre-commitHook脚本，使用Lint-staged代替原来的npmrunlint和npmrunformat命令：npxhuskyadd.husky/pre-commit"npxlint-staged"这样，当开发者执行gitcommit命令时，Husky会触发Lint-staged，只对本次提交的文件进行代码检查和格式化，提高检查效率。2.与CI/CD集成Husky可以与CI/CD工具（如GitHubActions、GitLabCI、Jenkins等）集成，实现自动化的工作流。以下以GitHubActions为例，介绍Husky与CI/CD集成的具体步骤：步骤1：创建GitHubActions配置文件在项目根目录下创建.github/workflows文件夹，并在其中创建一个ci.yml文件，配置GitHubActions的工作流：name:CIon:push:branches:[main,develop]pull_request:branches:[main,develop]jobs:build:runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-name:SetupNode.jsuses:actions/setup-node@v4with:node-version:'20'-name:Installdependenciesrun:npminstall-name:Runlintrun:npmrunlint-name:Runtestrun:npmruntest-name:Buildrun:npmrunbuild上述配置表示，当代码推送到main或develop分支，或者有针对这两个分支的PullRequest时，GitHubActions会自动触发CI流程。流程包括：拉取代码、设置Node.js环境、安装依赖、运行ESLint检查、运行单元测试、构建项目。步骤2：确保Husky在CI环境中正常运行由于Husky是在本地Git仓库中运行的，而CI环境通常是一个干净的环境，需要确保Husky在CI环境中能够正常启用。可以在package.json的prepare脚本中添加条件判断，确保在CI环境中也能启用Husky：{"scripts":{"prepare":"huskyinstall||true"}}上述配置表示，无论huskyinstall命令是否成功，都不会导致CI流程失败。这样，在CI环境中，Husky会被自动启用，并且在代码提交或推送时触发相应的Hook脚本。3.与自定义脚本集成除了与上述工具集成外，Husky还可以与自定义脚本集成，实现一些特定的功能。例如，在代码提交前自动更新项目的版本号、在代码推送后自动发送通知等。以下是一个简单的示例，展示如何在pre-commitHook中运行自定义脚本：步骤1：创建自定义脚本在项目根目录下创建一个scripts文件夹，并在其中创建一个update-version.js文件，编写自定义脚本：constfs=require('fs');constpath=require('path');//读取package.json文件constpackageJsonPath=path.resolve(__dirname,'../package.json');constpackageJson=JSON.parse(fs.readFileSync(packageJsonPath,'utf8'));//更新版本号constversionParts=packageJson.version.split('.');versionParts[2]=parseInt(versionParts[2])+1;packageJson.version=versionParts.join('.');//写入package.json文件fs.writeFileSync(packageJsonPath,JSON.stringify(packageJson,null,2));console.log(`版本号已更新为：${packageJson.version}`);上述脚本会读取package.json文件中的版本号，将补丁版本号加1，然后写回package.json文件。步骤2：修改pre-commitHook修改pre-commitHook脚本，在其中添加运行自定义脚本的命令：npxhuskyadd.husky/pre-commit"nodescripts/update-version.js&&npmrunlint"这样，当开发者执行gitcommit命令时，Husky会先运行自定义脚本更新版本号，然后运行ESLint检查代码。五、Husky常见问题与解决方案1.Hook脚本不触发在配置Husky的过程中，可能会遇到Hook脚本不触发的问题。以下是一些常见的原因和解决方案：原因1：Husky未正确启用如果在执行gitcommit或gitpush命令时，Hook脚本没有触发，首先需要检查Husky是否已经正确启用。可以通过以下命令检查Husky的状态：npxhuskystatus如果Husky未启用，可以手动执行npxhuskyinstall命令启用Husky，或者检查package.json中的prepare脚本是否配置正确。原因2：Hook脚本权限问题Hook脚本必须具有可执行权限才能被Git触发。可以通过以下命令检查Hook脚本的权限：ls-la.husky/如果Hook脚本没有可执行权限，可以使用以下命令添加可执行权限：chmod+x.husky/pre-commit.husky/commit-msg.husky/pre-push原因3：Git配置问题Git可能会忽略自定义的Hook脚本，可以通过以下命令检查Git的配置：gitconfigcore.hooksPath如果输出为空或不是.husky文件夹路径，可以使用以下命令设置Git的hooks路径：gitconfigcore.hooksPath.husky2.提交信息检查失败当提交信息不符合规范时，commit-msgHook会阻止提交并提示错误信息。以下是一些常见的提交信息检查失败的原因和解决方案：原因1：提交信息格式不正确如果提交信息没有遵循type(scope):subject的格式，会导致检查失败。例如，提交信息为“修复了一个bug”，没有指定类型和范围，就会被commitlint拒绝。解决方案是按照规范的格式编写提交信息，如fix(login):修复登录页面验证码错误问题。原因2：提交信息类型不合法commitlint定义了一些合法的提交类型，如feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert等。如果使用了不合法的类型，会导致检查失败。解决方案是使用合法的提交类型，或者在commitlint.config.js文件中配置自定义的提交类型。原因3：提交信息描述不符合要求提交信息的描述部分必须是一个简短的句子，首字母小写，结尾不使用句号。如果描述部分不符合要求，也会导致检查失败。解决方案是按照要求编写提交信息的描述部分，如“添加用户管理模块的增删改查功能”。3.代码检查耗时过长当项目规模较大时，在pre-commit阶段运行ESLint检查可能会耗时过长，影响开发效率。以下是一些解决方案：方案1：使用Lint-staged如前所述，Lint-staged可以只对本次提交的文件进行代码检查和格式化，而不是对整个项目的文件进行检查，从而提高检查效率。可以按照前面介绍的方法集成Lint-staged。方案2：配置ESLint缓存ESLint支持缓存功能，可以只检查修改过的文件，而不是每次都检查所有文件。可以在ESLint配置文件中开启缓存功能：module.exports={cache:true,cacheLocation:'.eslintcache'};开启缓存后，ESLint会将检查结果缓存到.eslintcache文件中，下次检查时只需要检查修改过的文件，提高检查效率。方案3：使用增量检查工具可以使用一些增量检查工具，如eslint-plugin-only-warn，将ESLint的错误转换为警告，这样在代码提交时不会因为一些非关键性的错误而阻止提交，同时在CI环境中进行严格的检查。或者使用eslint-scope等工具，只检查本次提交的文件中涉及的代码范围，减少检查的工作量。六、Husky进阶配置与优化1.自定义Hook脚本除了使用Husky提供的默认Hook脚本外，还可以编写自定义的Hook脚本，实现一些特定的功能。以下是一个自定义pre-commitHook脚本的示例，用于检查提交的文件中是否包含敏感信息：#!/usr/bin/envsh."$(dirname--"$0")/_/husky.sh"#检查提交的文件中是否包含敏感信息SENSITIVE_KEYWORDS=("password""secret""token""api_key")FILES=$(gitdiff--cached--name-only)forFILEin$FILES;doforKEYWORDin"${SENSITIVE_KEYWORDS[@]}";doifgrep-qi"$KEYWORD""$FILE";thenecho"错误：文件$FILE中包含敏感信息'$KEYWORD'，请检查后再提交。"exit1fidonedone上述脚本会在pre-commit阶段检查本次提交的文件中是否包含password、secret、token、api_key等敏感关键词，如果包含，会阻止提交并提示错误信息。2.多环境配置在实际项目中，可能需要根据不同的环境（如开发环境、测试环境、生产环境）配置不同的Husky规则。可以通过环境变量来实现多环境配置。以下是一个示例：步骤1：在package.json中添加环境脚本{"scripts":{"lint:dev":"eslint.--ext.js,.jsx,.ts,.tsx--config.eslintrc.dev.js","lint:prod":"eslint.--ext.js,.jsx,.ts,.tsx--config.d.js"}}上述配置定义了两个不同的lint脚本，分别用于开发环境和生产环境，使用不同的ESLint配置文件。步骤2：修改pre-commitHook脚本修改pre-commitHook脚本，根据环境变量选择不同的lint脚本：#!/usr/bin/envsh."$(dirname--"$0")/_/husky.sh"if["$NODE_ENV"="production"];thennpmrunlint:prodelsenpmrunlint:devfi这样，当在生产环境中执行gitcommit命令时，会运行npmrunlint:prod命令，使用生产环境的ESLint配置；在开发环境中执行gitcommit命令时，会运行npmrunlint:dev命令，使用开发环境的ESLint配置。3.性能优化为了提高Husky的运行性能，可以采取以下一些优化措施：措施1：减少Hook脚本的执行时间尽量简化Hook脚本中的逻辑，避免在Hook脚本中执行耗时的操作。例如，在pre-commit阶段只进行必要的代码检查和格式化，避免运行复杂的测试或构建任务。措施2：并行执行脚本可以使用一些工具（如concurrently）并行执行多个Hook脚本，