lint-staged配置踩坑指南从入门到实战优化

一个看似简单的工具，结果踩了不少坑

最近重构了一个老项目，代码质量实在是看不下去了。项目组里几个人的代码风格五花八门，提交的代码经常出现格式问题，还有些低级错误。领导催着要做代码规范，我就想着引入eslint + prettier + lint-staged这套组合拳。

开始我以为就是个简单的配置问题，结果实际操作起来发现坑还挺多的。特别是lint-staged这个工具，在项目初期配置的时候各种不顺，折腾了两天才搞定。

基本配置倒是不难

安装依赖这一步倒是没啥问题：

npm install --save-dev lint-staged eslint prettier husky

然后在package.json里加了个简单的配置：

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

这样配置后，每次提交的时候就会自动修复js文件的代码问题，格式化prettier支持的文件，然后重新add到暂存区。

真正的麻烦从这里开始

项目中遇到了第一个问题：某些文件特别大，比如生成的bundle.js，一万多行代码，eslint跑一遍要十几秒，提交被卡住。后来调整了配置，排除了一些不需要检查的文件：

{
  "lint-staged": {
    "!(*.min.js|bundle.*)": {
      "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write", "git add"]
    },
    "*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write",
      "git add"
    ],
    "*.{css,scss,json,md}": [
      "prettier --write",
      "git add"
    ]
  }
}

但是这样配置还是有问题，后来发现lint-staged的配置语法不是这么写的。重新查了文档，改成这样：

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

然后通过.gitignore和.eslintignore来排除不需要处理的大文件。

性能问题真的让人头疼

最大的坑来了。项目里的代码量不小，大概几千个js文件，每次提交都会触发lint-staged，虽然只处理暂存区的文件，但对于一些大型组件来说，eslint的检查还是很慢。

开始我没注意这个问题，有个同事提交了一次包含20多个大文件的修改，整个提交过程跑了快3分钟，大家都等着，场面一度很尴尬。

后来我意识到需要优化性能。首先是调整eslint规则，把一些非必要的检查项关掉：

// .eslintrc.js
module.exports = {
  extends: ['eslint:recommended'],
  rules: {
    // 一些耗时的规则关掉
    'no-console': 'off', // 这个其实不应该关，只是举个例子
    'complexity': 'off'
  },
  overrides: [
    {
      files: ['*.test.js', '*.spec.js'],
      rules: {
        // 测试文件用不同的规则
      }
    }
  ]
};

然后又尝试了并行执行的方式，但是发现lint-staged本身就有并发处理机制，主要瓶颈还是在eslint的解析速度上。

husky的配合也费了点劲

配好lint-staged后还要跟git hook结合，这里又踩了个坑。一开始我是手动创建pre-commit钩子：

#!/bin/sh
npx lint-staged

但这样有个问题：如果node_modules被删除了，npx命令会找不到lint-staged，提交就会失败。后来改用husky来管理hooks：

npx husky install
npx husky add .husky/pre-commit "npx lint-staged"

这样即使node_modules被清空，husky也能正确处理路径问题。不过husky 6.x和7.x的配置方式不一样，我也踩过这个版本差异的坑。

特殊场景的处理

项目里有些配置文件是自动生成的，比如webpack的配置，这些文件不需要格式化。还有些第三方库的文件也不能通过eslint检查。

我用了这样的配置来处理：

{
  "lint-staged": {
    "!(node_modules)/**/*.{js,jsx,ts,tsx}": [
      "eslint --fix",
      "prettier --write",
      "git add"
    ],
    "*.{css,scss,json,md}": [
      "prettier --write",
      "git add"
    ]
  }
}

这样能排除node_modules目录下的文件。对于特定的生成文件，我在.prettierrc里加了exclude配置。

实际效果还行吧

经过这些调整，现在项目的代码提交规范多了。大部分的格式问题都能自动修复，低级错误也能及时发现。虽然偶尔还是会有一些性能问题，但比最初的时候好多了。

有个小问题是，有时候eslint修复的问题可能不是最优解，需要手动调整。但总体来说，自动化程度提高了很多，代码质量也稳定了不少。

团队成员适应这套流程花了大概一周时间，现在大家提交代码都很自觉，不用再手动格式化了。

一些遗留问题

说实话，还有一些小问题没完全解决。比如某些特殊类型的文件处理还是有点慢，大文件的eslint检查时间还是比较长。不过因为提交频率不高，影响不大，暂时就先这样用了。

还有一个问题是Windows和Mac环境下路径处理有时候会有差异，不过概率很低，目前还没碰到具体的案例。

总的来说还行

这套方案虽然折腾了些，但最终效果还是不错的。项目的代码质量确实提高了，团队协作也更顺畅了。当然，最重要的还是团队成员都要有代码规范的意识，工具只是辅助。

这个过程中踩的坑主要是性能问题和环境兼容性，其他的配置都还好。如果你也在考虑引入类似的代码质量管控方案，建议先在小项目里试试水，确认没问题再推广到大项目。

以上是我踩坑后的总结，希望对你有帮助。如果有更好的优化方案，欢迎交流讨论。