解决 lint-staged 在 Next.js 15 中的配置问题

在 monorepo 环境中使用 lint-staged 配合 Next.js 15 时，开发者可能会遇到一个常见问题：ESLint 检查虽然执行成功，但实际上并没有对代码进行任何修复操作。本文将深入分析这个问题的成因，并提供可靠的解决方案。

问题现象

当开发者在 Next.js 15 项目中配置 lint-staged 时，按照官方推荐的方式设置后，会发现以下情况：

1. 命令执行成功，没有报错
2. 终端显示 lint 检查通过
3. 但代码中的 ESLint 问题实际上并未被修复

问题根源

经过分析，这个问题主要与 Next.js 15 的 lint 命令在 monorepo 环境中的工作方式有关。在 monorepo 结构中，项目路径层级较深，Next.js 的 lint 命令可能无法正确识别当前工作目录。

默认情况下，当使用 next lint --fix --file 命令时，如果没有明确指定工作目录（--dir 参数），Next.js 可能无法正确定位到项目的根目录，导致 lint 修复操作实际上没有执行。

解决方案

修改 lint-staged 配置文件，在 Next.js lint 命令中显式指定工作目录：

const path = require('path');

const buildEslintCommand = (filenames) =>
  `next lint --fix --dir . --file ${filenames.map((f) => path.relative(process.cwd(), f)).join(' --file ')}`;

module.exports = {
  '*.{ts,tsx}': ['prettier --write', buildEslintCommand],
};

关键修改点是在命令中添加了 --dir . 参数，明确告诉 Next.js 在当前目录下执行 lint 操作。

技术原理

1. --dir . 参数的作用：这个参数明确指定了 Next.js 应该在当前工作目录（即 monorepo 中的子项目目录）下执行 lint 操作，而不是尝试从 monorepo 根目录查找配置。

2. 路径解析：path.relative(process.cwd(), f) 确保了文件路径是相对于当前工作目录的相对路径，这对于 monorepo 中的子项目特别重要。

3. 执行上下文：lint-staged 会自动将命令的执行上下文设置为包含配置文件的目录（即 Next.js 项目目录），但 Next.js 的 lint 命令需要显式知道这一点才能正确工作。

最佳实践建议

1. 版本兼容性检查：这个问题在 Next.js 15 的候选版本中出现，建议检查使用的 Next.js 版本是否稳定。

2. monorepo 配置：在 monorepo 中，每个子项目应该有自己独立的 lint-staged 配置，而不是依赖根目录配置。

3. 调试技巧：当遇到类似问题时，可以使用 --debug 参数运行 lint-staged 来获取详细日志，帮助诊断问题。

4. 命令顺序：保持 prettier --write 在 ESLint 之前运行，可以避免格式问题干扰 ESLint 的检查。

总结

在 monorepo 中使用 lint-staged 和 Next.js 时，明确指定工作目录是确保 ESLint 修复功能正常工作的关键。这个小技巧可以节省开发者大量的调试时间，确保代码质量工具链的顺畅运行。随着 Next.js 版本的迭代，这个问题可能会在未来的版本中得到官方修复，但在当前版本中，添加 --dir . 参数是最可靠的解决方案。