企业官网建设流程全解析

打开终端，执行一次git commit，代码没提交成功，先被拦下来的是eslint和prettier的检查结果。这个场景在近几年的前端项目里太常见了，背后负责“拦人”的，就是 Husky 和它管理的 Git hooks 脚本。如果你对 Husky 的理解还停留在“装完就能用”，或者正在被“hook 不生效”“同事的机器上跑不起来”这类问题折磨，这篇文章就是写给你看的。我会把 Husky 在脚本管理上做的事情拆开讲清楚，包括它和 Git hooks 的关系、底层实现逻辑、常见钩子的配置实战，以及我在真实项目里踩过的那些坑。

1. 为什么前端工程越来越离不开 Husky

1.1 一次提交背后的“质量关卡”

先还原一个日常开发画面。你改完一个功能，git add了五个文件，正准备提交，结果屏幕上弹出一行报错：

✖ eslint: src/utils/format.ts - error

提交被中断了。你很不爽，但也只能回去改代码。这个“提交被中断”的动作，就是 Git hooks 在起作用，而 Husky 则是把这些 hooks 变成前端工程标准配置的推手。

很多人把 Husky 简单理解成“一个拦截提交的工具”，这没错，但不完整。Husky 真正的价值在于：它让 Git hooks 的创建、同步、维护变成项目的一部分，而不是靠每个开发者手动往.git/hooks里塞脚本。没有 Husky 的时候，代码规范检查、提交信息校验、push 前跑测试这些事情，一个人写得挺好，换台机器或者换个同事，就全没了。

1.2 Husky 在整个 Git hooks 体系中的位置

要明白 Husky 在干什么，得先知道 Git hooks 是个什么东西。Git 允许你在特定的事件节点挂载自定义脚本，这些脚本存放在仓库的.git/hooks/目录下，文件名决定触发时机。常见的有：

Git 执行这些脚本的规则很简单：脚本退出码为 0，就继续；退出码非 0，就中止当前操作。Husky 做的就是帮你把这些脚本放到正确的位置，并且让它们在安装依赖时自动生效。

1.3 从“本地生效”到“全员生效”的跨越

手动写.git/hooks/pre-commit有个致命问题：.git目录不会被提交到远端，也不会被 clone 拉下来。这意味着你精心设计的检查脚本，到了同事电脑上就是不存在。Husky 把自己变成依赖安装在package.json里，通过 npm 的安装生命周期自动为你创建 hooks。只要npm install跑过，每个人的本地仓库就都有一份相同的检查逻辑。

这也是为什么 Husky 在前端工程化里几乎成了标配——它是少数几个能做到“配置一处，全员同步”的工具之一。理解了这层逻辑，再去看它的安装脚本和配置方式，思路就清晰了。

2. 从 Git hooks 到 Husky：安装与生效的底层逻辑

2.1 老版本的做法：侵入.git目录

Husky 经历过一次比较重要的版本迭代。在 v4、v5 那个时代，Husky 的安装脚本做的事情非常“暴力”：直接在.git/hooks/目录下写入文件，或者把 Git 的 hooks 路径重新指向到 Husky 管理的位置。

这种方式有个显而易见的副作用：一旦你删掉.git目录重新初始化仓库，或者某个工具重写了.git/hooks下的文件，Husky 的钩子就失效了。而且不同版本的 Husky 安装逻辑不一致，团队里两个人用不同 npm 版本装出来的效果都可能不同。所以后面 Husky 才做了重构，改成现在这套更干净，也更符合 Git 规范的方案。

2.2 现代 Husky 的做法：core.hooksPath指向项目目录

Git 提供了一个全局配置项core.hooksPath，允许你把 hooks 目录从默认的.git/hooks改到其他任意位置。现代 Husky 做的事情本质上是：

git config core.hooksPath .husky

运行之后，Git 在执行提交、推送这些操作时，会去.husky/目录下找对应的 hook 文件。这个目录是项目的一部分，可以被提交到远端仓库。所以当同事 clone 项目后执行npm install，Husky 的prepare脚本就会帮他把core.hooksPath指向本地的.husky目录。

这里有一个值得注意的细节：core.hooksPath是 Git 的本地配置，存在当前仓库的.git/config里，不会跟着项目代码走。所以“npm install 后自动生效”这一步，必须依赖 Husky 的安装脚本去执行git config。一旦跳过安装脚本，hook 就静默失效了，这是后面排查问题的关键线索之一。

2.3prepare脚本与团队的安装关系

打开一个接入了 Husky 的现代前端项目的package.json，你会看到这样一段：

{ "scripts": { "prepare": "husky" } }

npm 的prepare脚本会在npm install之后自动执行（本地安装时），Husky 的 CLI 就是靠这个入口完成初始化。顺带一提，prepare脚本在npm publish前也会执行，但正常开发场景下影响不大。

团队协作时，你只需要保证两件事：

1. package.json里有prepare脚本；
2. .husky/目录被正常提交到代码仓库。

只要这两点满足，新成员 clone 项目、执行npm install，husky 钩子就会自动就位。比老版本手动让每个人去跑npm install husky要可靠得多。

2.4 从 package.json 配置到文件式配置的变化

老版本 Husky 支持在package.json里写husky.hooks节点来声明钩子内容：

{ "husky": { "hooks": { "pre-commit": "npm run lint" } } }

现在的版本已经彻底转向了文件式配置，也就是每个 hook 对应.husky/下的一个文件。比如.husky/pre-commit：

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

这个变化不仅仅是形式上的。文件式配置有几个明显优势：hook 脚本可以直接用 shell 语法，逻辑复杂度不受 JSON 格式限制；文件名就是 hook 名，结构一眼就能看明白；每个 hook 的修改记录会在 Git 历史里体现得清清楚楚，review 代码的时候能看到这个钩子是谁加的、为什么加。从工程治理的角度来说，这比一行行挤在package.json里健康得多。

3. 高频 hook 实战：pre-commit、commit-msg、pre-push 的配置

知道了 Husky 的原理，我们来点实际的。以我目前维护的前端项目为例，一个比较合理的 hooks 组合长这样：

3.1 pre-commit + lint-staged 的代码检查流水线

pre-commit里有三个选择：检查全部代码、检查暂存区代码、什么都别查。“检查全部代码”听起来很严谨，但项目一大，全量 lint 一次动辄几十秒，极其影响开发体验。实际工程里更合理的是用lint-staged：只检查git add过的那部分文件。

lint-staged配合 Husky 的典型写法是，先安装依赖：

npm install --save-dev husky lint-staged npx husky init

.husky/pre-commit文件内容：

npx lint-staged

lint-staged的规则可以放在package.json里，也可以单独建.lintstagedrc文件。我习惯放在 package.json 中：

{ "lint-staged": { "*.{js,jsx,ts,tsx,vue}": ["eslint --fix", "prettier --write"], "*.{css,scss,less}": ["prettier --write"], "*.{json,md}": ["prettier --write"] } }

这里有个细节值得多说一句：eslint --fix会直接修改文件，修改后的内容又被 lint-staged 自动重新暂存，所以提交进去的是修好的代码。但如果你的编辑器不是自动保存风格，或者团队里有人没用 format-on-save，这个流程会在 commit 时帮你兜底，避免“本地代码格式一塌糊涂，提交前才发现”的尴尬。

3.2 commit-msg + commitlint 的提交信息规范

commit-msg钩子的触发时机是在提交信息已经写入之后、提交完成之前。它可以帮你挡住那些"fix bug""update"之类毫无意义的提交信息。我用的是约定式提交（Conventional Commits）规范，配合 commitlint 来做校验。

安装 commitlint：

npm install --save-dev @commitlint/cli @commitlint/config-conventional

.husky/commit-msg文件内容：

npx --no -- commitlint --edit "$1"

配置一个commitlint.config.js：

module.exports = { extends: ['@commitlint/config-conventional'] };

这个组合的效果是：提交信息必须以feat:、fix:、docs:、chore:等类型开头，比如feat: 用户模块新增导出功能。如果格式不对，commit 直接被拒绝。这个钩子刚上线的头两天，团队肯定有人抱怨“提交个代码怎么这么麻烦”，但坚持两周后，你去看 Git 历史，那种整齐划一的提交记录，会让你觉得当时顶住压力是对的。

3.3 pre-push 的回归测试与性能控制

pre-push是我的最后一道安全网。和pre-commit不同，push 的触发频率远低于 commit，所以可以放入更重的操作，比如跑一遍完整的单元测试。.husky/pre-push：

npm run test

但这里有个现实的考量：如果项目测试用例特别多，每次 push 都跑全量测试，团队成员会非常暴躁。我见过一些团队把pre-push里的测试精简成“只跑受影响模块的测试”或者“只跑类型检查”。比如：

npm run typecheck

TS 项目尤其推荐这个。typecheck虽然也要几十秒，但比全量测试轻得多，又能拦住大量低级类型错误。如果你维护的是规模较大的项目，可以根据实际情况调整，核心原则是：这个 hook 应当抓住真正的硬错误，而不应该变成一个消耗耐心的瓶颈。

3.4 一个值得直接复制的完整组合

把上面几个串起来，一个中等规模的 TypeScript 前端项目，最终 hooks 配置大致是：

.husky/ ├── pre-commit -> npx lint-staged ├── commit-msg -> npx --no -- commitlint --edit "$1" └── pre-push -> npm run typecheck

依赖清单：

npm install --save-dev husky lint-staged @commitlint/cli @commitlint/config-conventional

这套组合跑了大半年，最直观的感受是：code review 的时候几乎看不到“顺手改了个缩进”“漏了分号”这类琐碎问题，注意力能全部放在逻辑本身。这就是 hooks 带来的隐形收益——它把审查者的时间还给了真正需要人判断的地方。

4. 钩子不触发的排查链路：从现象到根因

Husky 这类工具装好之后，最大的噩梦就是“明明配置了，但提交的时候没有任何反应”。我处理过的 hook 失效问题多了，基本可以归纳成下面这条完整的排查链路。

4.1 先复现：手动执行 hook 脚本

遇到 hook 不生效，别急着改配置。先把问题缩小到“是脚本本身不执行，还是日志没显示”。直接手动执行一次 hook 文件：

sh .husky/pre-commit

如果手动执行时脚本报错，那说明问题在 shell 命令本身；如果手动执行一切正常，问题大概率出在 Git 没有调用这个 hook。这一步能帮你快速划分排查方向，避免在错误的方向上折腾半天。

4.2 检查core.hooksPath与目录结构

Git 没有调用 hook，最常见的根因就是core.hooksPath没有正确指向.husky。执行：

git config core.hooksPath

正常情况下会输出.husky。如果输出为空，或者指向了其他目录，说明 husky 的初始化没有成功执行或者被其他配置覆盖了。修复方式很简单，手动执行一次：

git config core.hooksPath .husky

但这里不要停留在“改好就行”的层面，还要问一句为什么会被改掉。我遇到过的真实情况包括：同事手动执行了某个工具的命令，该工具顺手改了core.hooksPath；还有人用了老版本的 husky 初始化命令。排查时要顺藤摸瓜，找到是谁改的，免得下次又被重置。

还需要确认.husky/目录下的文件确实存在，并且文件名拼写正确。Git 对 hook 文件名是大小写敏感的，pre-commmit少一个 m，或者写成Pre-commit，都静默不执行。

4.3 检查安装流程与 npm 生命周期

如果core.hooksPath是对的，hook 文件也存在，但 Git 操作时还是没反应，那就要看安装环节了。重点检查两件事：

1. package.json里的prepare脚本还在不在；
2. 上一次npm install是否完整执行。

有一个很常见的坑：同事的 npm 配置了ignore-scripts=true，npm install 时一律跳过生命周期脚本，husky 的 prepare 根本没跑。这时候你在他那台机器上git config core.hooksPath多半是空的，或者指向了旧路径。让他把ignore-scripts关掉重新执行 install 即可。

还有一个隐蔽的坑是 npm 的缓存。某些情况下，老版本的 husky 被缓存了，新加的 hook 文件没有正常创建出来。处理方式是清理 npm 缓存后重新 install：

npm cache verify npm install

4.4 非法跳过与绕过：--no-verify和HUSKY=0

有些“hook 不生效”其实不是失效，而是被人为绕过了。git commit --no-verify会跳过所有客户端 hook，git push --no-verify同理。Husky 本身也支持通过环境变量HUSKY=0临时禁用所有钩子。

举个例子：

HUSKY=0 git commit -m "紧急修复"

这条命令会直接跳过 pre-commit 和 commit-msg，让提交成功。我不反对紧急情况下用这个开关，但强烈建议在团队规范里明确：--no-verify只能用于刻不容缓的救火场景，并且事后必须补上对应的检查。否则“反正可以绕过”会成为习惯，hook 的存在意义就瓦解了。

排查这类情况时，可以看下 shell 历史记录或者 CI 日志，确认是不是有人用了跳过参数。

5. 团队规范与 CI 协作：让 Husky 成为项目资产

5.1 如何让新同事 clone 后自动具备 hooks

Husky 最容易被低估的一点，就是它的“传染性”。只要package.json的prepare脚本和.husky/目录都进了仓库，那么新成员 clone 项目后执行一遍npm install，一切就自动就位。这个体验在新老成员之间是完全一致的——这正是它取代手动配置.git/hooks的根本原因。

但要注意一个例外情况：如果你的项目用的是 pnpm，并且启用了ignoredBuiltDependencies之类的过滤机制，husky 的依赖安装可能被跳过。具体表现同样是 hook 不生效。解决办法是在项目初始化时把 husky 加入允许列表，或者让成员手动执行pnpm rebuild husky。这类问题在 macOS 和 Windows 上还可能因为 shell 环境不同出现差异，排查时要多留个心眼。

5.2 CI 中处理 hooks 的正确姿势

很多团队上来就把 Husky 装好，结果 CI 里跑npm install时又执行了一遍 hooks，导致流水线偶尔因为环境差异被莫名卡住。实际上，CI 环境里根本不需要跑这些客户端 hook，因为提交代码的人已经在本地被检查过了。

推荐的做法是在 CI 脚本中显式关闭：

# .github/workflows/ci.yml 或对应 CI 配置 env: HUSKY: 0

这行配置让 husky 在 CI 环境内完全静默，既不会干扰安装流程，也不会在流水线的构建步骤里多出不必要的检查。记住一个原则：本地做质量拦截，CI 做最终验证。两端分工明确，才不会互相打架。

5.3 本地环境差异与规避方案

前端团队的开发环境远比想象中复杂，有人用 macOS，有人用 Windows，有人用 WSL。Husky 生成的 hook 文件本质是 shell 脚本，Windows 环境尤其容易出现执行权限或路径解析问题。

规避方案主要有三种：

1. 保持 hook 文件内部的 shell 脚本尽量简洁，不要写复杂的管道、grep、awk 逻辑；
2. 把复杂检查逻辑收敛到 npm scripts 或 node 脚本里，hook 文件只保留一行调用；
3. 在团队共享的开发文档里，写清楚 Windows/WSL 下的安装注意事项。

我自己遇到过一次比较经典的坑：某成员在 Windows 上用系统的 Git Bash，npx husky init生成的文件没有可执行权限，导致 hook 静默失效。最后通过给.husky/下的文件手动追加执行权限解决：

chmod +x .husky/pre-commit .husky/commit-msg .husky/pre-push

这个操作在 macOS 和 Linux 上通常不会遇到，但 Windows 环境真的要格外注意。

6. 我踩过的坑和几个提升体验的小细节

6.1 lint-staged 与 stash：未暂存改动丢失的惊吓

lint-staged 在处理暂存区时，会利用 Git 的 stash 机制临时保存未暂存的改动，等 lint 完成后再恢复。有一个版本出现过一种情况：如果你的未暂存改动包含了会引发 lint 错误的代码，而暂存区是干净的，lint-staged 可能把这些改动混进来，导致现场看起来很乱。

我的经验是：提交前尽量保持工作区是干净或基本可控的状态。不要养成“先随便 add 一部分，留着一大堆改动继续写”的习惯。这不仅是 lint-staged 的策略问题，更是 Git 使用的健康习惯。

6.2 给 hook 加上可读性输出

Husky 拦截住提交时，默认输出往往是 lint 的错误信息，但那是给机器看的，不是给人看的。我习惯在 hook 脚本开头加一段友好提示，告诉当前开发者发生了什么、该怎么处理。

比如.husky/pre-commit可以写成：

npx lint-staged || { echo "代码格式有问题，先执行 npm run lint:fix 修复，再重新 add 和 commit。" exit 1 }

团队里有新人时，这类提示能大幅降低不知所措的概率。而且加了这段逻辑，还避免了 lint-staged 失败后 Git 抛出一堆令人困惑的底层报错，直接面对问题核心。

6.3 不要把所有检查都塞进 hook

最后想说一个关于“度”的建议。Husky 是很好的质量闸门，但不要把它变成全体开发者的枷锁。我见过有的项目在 pre-commit 里同时跑 eslint、stylelint、prettier、tsc、单测，提交一次要等五分钟。这样做的结果是：大家为了省时间，要么频繁使用--no-verify，要么手动把 hook 关掉。当一个工具开始被高频规避时，它就已经失去了约束力。

合理的做法是，把检查按“提交时”和“推送时”拆分：提交时跑轻量级的暂存区检查和提交信息校验；推送时跑成本更高但能兜底的类型检查或关键模块测试。这个分工既能覆盖大部分问题，又不会让开发者觉得每一步都在过安检。

6.4 一个小技巧：手动维护 hook 文件的版本演进

Husky 的 hook 文件本身就是项目代码的一部分，所以它也应该走 code review 流程。团队里在调整.husky/目录下的脚本时，我会在 PR 描述中附带一段验证说明，比如“在 macOS 和 WSL 下各跑了一次提交验证通过”。这样能提前暴露跨平台兼容层面的大多数隐性问题。毕竟，hook 文件失效的代价不是报错，而是毫无提示地失去一道保护网。

这一路用下来，Husky 给我的整体感受是：它本身不复杂，复杂的是你如何设计这套脚本组合、如何把团队协作的规则固化下来、如何在出问题时快速定位是环境还是配置的原因。把这个工具吃透了，你收获的其实不是某一条命令的用法，而是一套关于“如何在代码入库前设卡”的完整实践思路。