解决 90% 的代码规范问题：lint-staged 最佳实践

解决 90% 的代码规范问题：lint-staged 最佳实践

【免费下载链接】lint-staged 项目地址: https://gitcode.com/gh_mirrors/lin/lint-staged

在多人协作项目中，代码提交前的格式校验和修复往往耗费大量精力。开发者可能忘记运行 linter，或因配置不一致导致代码风格混乱。lint-staged 作为一款专注于 Git 暂存文件的自动化工具，能在提交前自动校验并修复代码问题，显著提升团队协作效率。

核心价值：为什么需要 lint-staged？

传统的代码校验工具（如 ESLint、Prettier）需手动触发或全局扫描，效率低下且易遗漏。lint-staged 通过以下特性解决痛点：

• 定向校验：仅处理 Git 暂存区文件，避免全项目扫描
• 自动化修复：自动应用 --fix 修复格式问题，并提交更改
• 多工具集成：支持 ESLint、Prettier、Stylelint 等主流工具链
• 零侵入配置：与 Git 钩子（如 pre-commit）无缝集成，不改变开发流程

快速上手：3 步完成基础配置

安装依赖

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

配置 Git 钩子

在 package.json 中添加配置：

{
  "scripts": {
    "prepare": "husky install"
  },
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"],
    "*.{css,scss}": ["stylelint --fix", "prettier --write"],
    "*.md": ["prettier --write"]
  }
}

启用钩子

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

工作原理：从暂存到提交的全流程

lint-staged 的核心逻辑位于 lib/gitWorkflow.js 和 lib/getStagedFiles.js。其工作流程如下：

1. 获取暂存文件：通过 git diff --staged 命令提取暂存区文件列表
2. 模式匹配：根据配置的 glob 规则（如 *.js）匹配文件类型
3. 执行任务链：按顺序运行校验/修复命令（如 eslint --fix）
4. 自动提交：将修复后的文件重新添加到暂存区

高级技巧：解决复杂场景问题

处理大型文件集

当暂存文件过多时，可通过 chunkFiles 配置分片处理：

// lint-staged.config.js
export default {
  "*.js": (files) => files.map(file => `eslint --fix ${file}`),
  "*.{png,jpg}": {
    commands: "imagemin --out-dir=dist/images",
    chunkSize: 10
  }
}

忽略特定文件

使用函数配置动态过滤文件：

// lint-staged.config.js
import micromatch from 'micromatch'

export default {
  "*.js": (files) => {
    const filtered = micromatch.not(files, ['*test.js', 'vendor/**'])
    return `eslint --fix ${filtered.join(' ')}`
  }
}

集成 TypeScript 类型检查

添加增量类型检查以提升性能：

{
  "lint-staged": {
    "*.{ts,tsx}": [
      "eslint --fix",
      "prettier --write",
      () => "tsc --noEmit --incremental"
    ]
  }
}

常见问题与解决方案

部分暂存文件冲突

当文件同时存在暂存和未暂存更改时，lint-staged 会自动创建补丁文件保存未暂存内容，避免冲突。相关逻辑见 lib/gitWorkflow.js 中的 prepare 方法。

二进制文件处理

通过 --diff-filter 参数排除二进制文件：

npx lint-staged --diff-filter=ACMR

调试模式

使用 DEBUG 环境变量查看详细执行过程：

DEBUG=lint-staged* npx lint-staged

最佳实践清单

1. 分层配置：在 monorepo 项目中，于子包目录放置独立 .lintstagedrc
2. 命令顺序：先运行代码修复（eslint --fix），再执行格式化（prettier）
3. 并发控制：通过 --concurrent false 解决工具间文件竞争问题
4. 版本控制：将 .husky 目录和配置文件纳入 Git 管理，确保团队一致

通过以上配置，团队可将代码规范问题拦截在提交前，减少 90% 以上的代码格式相关沟通成本。结合 官方文档 中的示例，可进一步扩展工具链能力，如集成单元测试、CSS 前缀自动补全等功能。

【免费下载链接】lint-staged 项目地址: https://gitcode.com/gh_mirrors/lin/lint-staged