Git提交前自动美化JS代码：Husky与lint-staged配置教程

缩略图：Git 提交前代码自动格式化完整链路架构

在 JavaScript 团队协作中，代码格式混乱和提交前的繁琐格式化常导致冲突与低效。本文将通过 Husky 9 与 lint-staged 的标准化配置，为项目搭建一套在键入 git commit 时自动美化暂存区 JavaScript 代码的自动化机制，使格式修复在提交瞬间无感完成，杜绝不规范代码流入代码仓库。

一、工作原理：Husky 与 lint-staged 的分工协作

单纯依靠开发者在编辑器中“保存时自动格式化”，无法保证所有团队成员的环境配置完全一致；而在 CI/CD 阶段拦截格式错误，又会因为漫长的构建反馈周期打断开发节奏。最合理的防线是在本地执行 git commit 的瞬间完成校验与修正。

实现这一目标的核心是两个工具的精确分工：

• Husky：充当 Git Hooks 的管理桥梁。原生的 Git 钩子脚本存放在 .git/hooks/ 目录下，默认不会提交到远程仓库。Husky 通过配置将钩子目录映射到项目的版本控制中，让团队共享统一的提交钩子（例如 pre-commit）。
• lint-staged：充当高效的过滤器与执行器。如果每次提交都用 Prettier 全量扫描整个项目的几十万行代码，提交过程将变得极其缓慢。lint-staged 专门从 Git 暂存区中筛选出本次被修改的文件，并仅对符合规则（如 *.js）的暂存文件执行美化命令，随后将美化后的结果重新放回暂存区。

图 1：Git 提交时 Husky 与 lint-staged 的调用时机与数据流向

二、从零搭建：完整配置步骤

配置过程分为依赖安装、格式化规则定义、Husky 初始化以及挂载 Hook 四个实际步骤。执行前请确保当前工程根目录下已存在 package.json 且已完成 git init。

步骤 1：安装依赖包

在项目根目录运行安装命令。我们将 husky、lint-staged 和 prettier 安装在 devDependencies 开发依赖中：

# 使用 npm
npm install --save-dev husky lint-staged prettier

# 或使用 pnpm
pnpm add -D husky lint-staged prettier

# 或使用 yarn
yarn add -D husky lint-staged prettier

步骤 2：配置 Prettier 代码美化规则

在项目根目录创建 .prettierrc.json 文件，根据团队需要指定代码风格（例如单引号、行尾分号、缩进空格数）：

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5",
  "printWidth": 80
}

同时建议创建 .prettierignore 文件，排除编译产物和依赖目录：

node_modules
dist
build
coverage

步骤 3：配置 lint-staged 匹配规则

打开 package.json，在顶层添加 lint-staged 字段。该字段的值是一个对象，键为匹配文件的 Glob 模式，值为待执行的命令：

{
  "name": "my-project",
  "version": "1.0.0",
  "devDependencies": {
    "husky": "^9.0.0",
    "lint-staged": "^15.0.0",
    "prettier": "^3.0.0"
  },
  "lint-staged": {
    "*.{js,jsx,mjs,cjs}": [
      "prettier --write"
    ]
  }
}

步骤 4：初始化 Husky 并创建 pre-commit 钩子

Husky 从 9.x 版本开始提供了极度简化的初始化方式，只需一条命令即可完成 Git 钩子路径绑定和示例脚本创建：

# 初始化 husky 并自动在 package.json 中配置 prepare 脚本
npx husky init

该命令会执行两项修改：

1. 在项目根目录下生成 .husky/ 文件夹，并在其中创建 .husky/pre-commit 模板文件；
2. 在 package.json 的 scripts 中自动添加 "prepare": "husky"，确保其他开发者在执行 npm install 时能够自动激活本地钩子。

接着，修改生成的 .husky/pre-commit 文件，将其内容替换为调度 lint-staged 的命令：

npx lint-staged

图 2：Husky 与 lint-staged 的安装初始化与配置流程

三、核心差异：为什么必须使用 lint-staged？

有初学者会提出疑问：“既然已经在 .husky/pre-commit 里拦截了提交，为什么不直接运行 npx prettier --write .，而一定要引入一个看似多余的 lint-staged 呢？”

直接在 pre-commit 中执行全量扫描会导致以下三个严重的工程问题：

1. 执行耗时巨大：在成千上万个文件的大型仓库中，全量格式化可能耗费十几秒甚至数分钟，每次提交都会造成令人烦躁的卡顿。而 lint-staged 仅扫描本次修改的 2~3 个文件，耗时通常在 200 毫秒以内。
2. 污染历史记录与 Git Blame：全量格式化会把同事未提交的旧代码或历史遗留文件一并改写，导致代码行的修改责任人（git blame）全部被篡改为当前提交者，严重破坏排查缺陷时的追溯链条。
3. 部分暂存（Partially Staged）的安全保护：开发者经常使用 git add -p 仅暂存文件的某些代码块，将另一些实验代码留在工作区。全量格式化会直接冲掉这种微妙的状态，而 lint-staged 内部具备 Stash 备份机制，能仅对暂存区内的差异执行修正，保护工作区尚未暂存的代码完好如初。

图 3：全量处理与 lint-staged 增量处理的核心差异对比

四、实际效果验证与演练

配置完成后，我们可以通过一个故意写得不规范的 JavaScript 文件，验证自动化流线是否正常工作。

1. 编写一份格式混乱的 JavaScript 代码

在项目目录下创建 src/index.js，故意留下杂乱的缩进和双引号：

// 原始文件：格式不规则
const   calculateTotal  = (price,count)=>{
if(count<=0){
return 0
}
  return    price*count;
}

calculateTotal(  100,  2)

2. 执行暂存并尝试提交

在终端中执行 Git 命令：

git add src/index.js
git commit -m "feat: 添加总价计算函数"

3. 观察控制台输出

此时终端会输出如下控制台信息（示例输出）：

✔ Preparing lint-staged...
✔ Running tasks for staged files...
  ❯ package.json — 1 file
    ❯ *.{js,jsx,mjs,cjs} — 1 file
      ✔ prettier --write
✔ Applying modifications from tasks...
✔ Cleaning up temporary files...
[main a1b2c3d] feat: 添加总价计算函数
 1 file changed, 7 insertions(+), 6 deletions(-)

4. 检查提交后的文件内容

无需手动执行任何美化指令，再次打开 src/index.js，代码已经被自动重整为完全符合 .prettierrc.json 规则的标准格式：

// 美化后的文件：提交已就绪
const calculateTotal = (price, count) => {
  if (count <= 0) {
    return 0;
  }
  return price * count;
};

calculateTotal(100, 2);

五、常见问题排查与工程化建议

在实际项目落地过程中，不同团队成员的本地环境可能存在细微差异。以下是三个最常见的配置问题及解决方案：

图 4：Husky + lint-staged 提交拦截决策与故障排查链路

团队规范建议：关于 --no-verify 的使用约束

Git 提供了 git commit --no-verify（简写为 -n）参数，允许跳过所有 pre-commit 钩子。虽然该参数在紧急排查系统故障时可以应急使用，但在常规业务迭代中应当在团队内部形成约定，禁止随意使用该参数绕过提交检查。只有将格式校验作为日常开发的不可逾越环节，团队代码库才能长期维持井然有序的状态。