理解 lint-staged 中自定义配置的工作原理

在 JavaScript 项目中，lint-staged 是一个非常有用的工具，它可以帮助开发者在提交代码前自动对暂存区的文件运行指定的 linter 和格式化工具。然而，很多开发者在配置 lint-staged 时会遇到一个常见问题：为什么直接运行命令能修复代码，但通过 lint-staged 运行时却不起作用？

问题本质

这个问题的核心在于对 lint-staged 配置工作原理的理解。lint-staged 提供了两种配置方式：

1. 简单配置：直接指定命令字符串，lint-staged 会自动将匹配的文件名附加到命令后面
2. 高级配置：使用函数自定义匹配逻辑，此时需要开发者自行处理文件名参数

配置差异解析

在简单配置中，lint-staged 会自动处理文件名的传递。例如：

{
  "*.js": "eslint --fix"
}

这种情况下，lint-staged 会自动将匹配的 JavaScript 文件名附加到 eslint --fix 命令后面。

但当使用 JavaScript 函数配置时，情况就不同了：

module.exports = (stagedFiles) => {
  const eslintFiles = stagedFiles.filter(/* 过滤逻辑 */);
  return eslintFiles.length > 0 ? ['eslint --fix'] : [];
}

这种配置方式下，lint-staged 认为返回的命令是完整的，不会自动附加文件名。因此，开发者需要自行处理文件名的传递：

module.exports = (stagedFiles) => {
  const eslintFiles = stagedFiles.filter(/* 过滤逻辑 */);
  return eslintFiles.length > 0 
    ? [`eslint --fix ${eslintFiles.join(' ')}`] 
    : [];
}

最佳实践建议

1. 明确配置类型：清楚自己使用的是简单配置还是高级函数配置
2. 文件名处理：在函数配置中，记得手动拼接文件名参数
3. 调试技巧：使用 --debug 标志运行 lint-staged 查看实际执行的命令
4. 配置验证：在修改配置后，使用简单案例测试确保功能正常

理解这个关键差异后，开发者就能更灵活地使用 lint-staged 的各种配置方式，充分发挥它在代码质量控制中的作用。