解决 lint-staged 与 ESLint 扁平配置格式的兼容性问题

在使用 lint-staged 工具配合 ESLint 的扁平配置格式(eslint.config.js)时，开发者可能会遇到"未找到匹配模式的文件"的错误提示。这种问题通常出现在配置不当的情况下，导致文件匹配和传递机制出现异常。

问题现象分析

当开发者尝试在项目中同时使用 lint-staged 和 ESLint 的扁平配置时，控制台会显示类似以下的错误信息：

No files matching the pattern "/path/to/file1 /path/to/file2" were found.
Please check for typing mistakes in the pattern.

这种错误表明 ESLint 无法正确识别 lint-staged 传递的文件路径参数，导致文件匹配失败。值得注意的是，直接运行 ESLint 命令时却可以正常工作，这说明问题出在 lint-staged 的配置方式上。

根本原因

问题的核心在于 lint-staged 的工作机制与配置方式不匹配。lint-staged 本身已经具备自动传递暂存文件列表的功能，但常见的错误配置方式会导致：

1. 重复的文件匹配模式：在 lint-staged 配置和 ESLint 命令中都指定了文件匹配模式
2. 不必要的中间脚本调用：通过 npm scripts 间接调用 ESLint，破坏了参数传递机制
3. 参数解析异常：多级命令调用导致文件路径参数被错误拼接

正确配置方案

正确的配置应该充分利用 lint-staged 的自动文件传递功能，简化配置结构：

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

这种配置的优势在于：

1. 直接调用 ESLint 可执行文件，避免中间层干扰
2. lint-staged 会自动将匹配的暂存文件列表附加到命令后面
3. 配置简洁明了，易于维护

配置原理详解

当使用上述精简配置时，lint-staged 的工作流程如下：

1. 检测 Git 暂存区中所有匹配 *.{js,json} 模式的文件
2. 将这些文件的完整路径收集起来
3. 执行 eslint --fix 文件1 文件2 文件3 这样的命令
4. ESLint 接收具体的文件路径进行处理

相比之下，原始的错误配置会导致 lint-staged 将文件路径作为额外参数附加到整个 npm 命令后面，造成 ESLint 无法正确解析这些路径参数。

最佳实践建议

1. 对于简单的项目，使用上述精简配置即可
2. 对于复杂项目，可以考虑将配置拆分到专门的 lint-staged 配置文件中
3. 确保项目中安装的 ESLint 版本支持扁平配置格式
4. 定期更新 lint-staged 和 ESLint 到最新版本，以获得最佳兼容性

通过理解 lint-staged 的工作机制和正确配置方式，开发者可以避免这类文件匹配错误，提高代码质量工具的效率和可靠性。