lint-staged 提交检查：只检查暂存文件

lint-staged 提交检查：只检查暂存文件

在团队协作中，代码风格统一和常见错误预防是保证代码库健康的关键。lint-staged 是一个在 Git 暂存文件上运行 linters 的工具，它只针对即将提交的文件进行检查，避免全量扫描带来的性能损耗。本教程将带你从零开始配置 lint-staged，并结合 husky 实现 Git 提交前的自动检查。

为什么选择 lint-staged

• 只检查变更：不用每次扫描整个项目，大幅缩短检查时间。
• 精准拦截：只对即将提交的文件运行校验，防止错误进入仓库。
• 可组合：可以同时运行 ESLint、Prettier、Stylelint 等多种工具。
• 自动修复：支持先自动修复再检查，减少手动修正。

前置准备：初始化项目

确保本地已安装 Node.js 和 Git，然后在项目根目录执行：

npm init -y
git init

第一步：安装 lint-staged 与 husky

lint-staged 需要配合 Git 钩子使用，最常用的搭档是 husky（v9+）。

npm install --save-dev lint-staged husky

初始化 husky，创建 .husky 目录并设置 pre-commit 钩子：

npx husky init

执行后，会生成 .husky/pre-commit 文件。编辑该文件，添加运行 lint-staged 的命令：

npx lint-staged

提示：如果你使用的是 pnpm 或 yarn，可相应使用 pnpm exec lint-staged 或 yarn lint-staged。

第二步：配置 lint-staged

在 package.json 中添加 lint-staged 字段，或者单独创建 .lintstagedrc / lint-staged.config.js 文件。下面以 package.json 为例：

{
  "lint-staged": {
    "*.js": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{css,scss}": "stylelint --fix",
    "*.{json,md}": "prettier --write"
  }
}

配置含义：

• 匹配到的文件将被传递给后面的命令。
• 命令可以是一个字符串或数组，数组中的命令会依次执行。
• 每个命令仅作用于被暂存的文件，而不是整个项目。

第三步：安装对应的 linter 和格式化工具

为了让配置生效，你需要安装并在项目中正确配置对应的工具。以 ESLint 和 Prettier 为例：

npm install --save-dev eslint prettier eslint-config-prettier

初始化 ESLint 配置（根据你的框架选择配置）：

npx eslint --init

创建 .prettierrc 文件并写入自定义规则，例如：

{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2
}

如果还有样式检查需求，可安装 stylelint：

npm install --save-dev stylelint stylelint-config-standard

第四步：测试 lint-staged

1. 创建一些测试文件并写入不合规范的代码。
2. 使用 git add 将它们添加到暂存区。
3. 执行 npx lint-staged 手动运行，观察输出。

echo "const x = 1" > test.js
git add test.js
npx lint-staged

如果配置正确，你会看到 ESLint 和 Prettier 的检查与修复过程。

第五步：验证提交流程

现在尝试正式提交代码：

git commit -m "test: lint-staged demo"

husky 会在提交前触发 pre-commit 钩子，进而运行 lint-staged。如果检查失败，提交将被阻止，你必须在修复错误后再次提交。

进阶配置技巧

使用函数动态生成命令

在 lint-staged.config.js 中，你可以导出函数来更灵活地控制命令：

module.exports = {
  '*.js': (filenames) => [
    `eslint --fix ${filenames.join(' ')}`,
    `prettier --write ${filenames.join(' ')}`,
  ],
};

仅检查不修复

有时你只希望检查而不自动修改文件，可以将 --fix 去掉或使用 --no-fix 参数：

{
  "*.js": "eslint"
}

对同一类文件运行多个命令

采用数组形式依次执行，前一个命令失败会阻止后续执行。若希望某个命令失败不影响后续，可以用 || true 或者使用 --no-stash 等控制（不推荐忽略重要错误）。

配合 TypeScript 项目

如果你的项目使用 TypeScript，可以加入类型检查：

{
  "*.{ts,tsx}": [
    "eslint --fix",
    "prettier --write",
    "tsc --noEmit"
  ]
}

注意 tsc --noEmit 会检查整个项目的类型，而不仅仅是暂存文件。为了只检查暂存文件，需要额外的工具如 tsc-files：

npm install --save-dev tsc-files

配置修改为：

{
  "*.{ts,tsx}": [
    "eslint --fix",
    "prettier --write",
    "tsc-files --noEmit"
  ]
}

常见问题排查

总结

通过 lint-staged 和 husky 的组合，你可以在不牺牲开发体验的前提下，将代码规范检查前置到提交环节。只检查暂存文件的设计让检查速度极快，同时确保进入仓库的每一行代码都经过验证。立即把它加入你的项目，让代码质量从源头得到保障。