Next.js 项目 ESLint 配置完全指南：从入门到实战🚀 前言最近在一个 Next.js 15.1.0 项

在 Next.js 项目开发中，ESLint 是保证代码质量的重要工具。本文将详细介绍如何在 Next.js 项目中正确配置 ESLint，以及如何解决常见的配置问题。

🚀 前言

最近在一个 Next.js 15.1.0 项目中配置 ESLint 时遇到了一系列问题，从 ESLint 9.x 的扁平配置格式不兼容，到插件冲突，再到 VS Code 扩展无法正常工作。经过一番折腾，总结出了这份完整的解决方案。

📋 项目环境

Next.js: 15.1.0
Node.js: 22.19.0
包管理器: pnpm
TypeScript: 5.5.4
ESLint: 8.57.0（最终选择）

🔧 ESLint 版本选择

ESLint 9.x vs 8.x 的选择

在配置过程中，我们遇到了 ESLint 版本选择的问题：

ESLint 9.x 的问题：

使用全新的扁平配置格式（Flat Config）
需要额外安装 @eslint/eslintrc 依赖
VS Code ESLint 扩展支持不完善
配置复杂度较高

ESLint 8.x 的优势：

使用传统的 .eslintrc.json 配置格式
VS Code 扩展支持完善
配置简单直观
社区生态成熟

最终选择：ESLint 8.57.0

{
  "devDependencies": {
    "eslint": "^8.57.0"
  }
}

⚙️ 配置步骤

1. 安装依赖

pnpm add -D eslint@^8.57.0 eslint-config-next@15.1.0

2. 创建 .eslintrc.json

{
  "extends": ["next/core-web-vitals"],
  "rules": {
    "no-unused-vars": "warn",
    "react/display-name": "off",
    "@next/next/no-img-element": "warn"
  }
}

3. VS Code 配置

创建 .vscode/settings.json：

{
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "typescript",
    "typescriptreact"
  ],
  "eslint.enable": true,
  "eslint.run": "onType"
}

4. package.json 脚本配置

{
  "scripts": {
    "lint": "next lint",
    "lint:fix": "next lint --fix"
  }
}

🐛 常见问题及解决方案

问题1: ESLint 9.x 扁平配置不兼容

错误信息：

Cannot find package '@eslint/eslintrc'

解决方案： 降级到 ESLint 8.x，使用传统配置格式。

问题2: 插件冲突

错误信息：

ESLint couldn't determine the plugin "react-hooks" uniquely

解决方案： 简化配置，只使用 next/core-web-vitals，避免重复引入插件。

问题3: VS Code 不显示错误提示

解决方案：

确保安装了 ESLint 扩展
配置 .vscode/settings.json
重启 VS Code 或执行 "Developer: Reload Window"

问题4: TypeScript 版本警告

警告信息：

WARNING: You are currently running a version of TypeScript which is not officially supported

解决方案： 这只是警告，不影响功能。如需消除，可降级 TypeScript 到 5.4.x。

📊 实际效果展示

配置完成后，运行 pnpm run lint 的输出：

./src/app/page.tsx
6:3   Error: 'CopilotKit' is defined but never used.  no-unused-vars
7:3   Error: 'useCoAgent' is defined but never used.  no-unused-vars
8:3   Error: 'useCopilotAction' is defined but never used.  no-unused-vars

./src/components/AIHeader/index.tsx
20:11  Error: 'isSmallScreen' is assigned a value but never used.  no-unused-vars
193:29 Error: 'e' is defined but never used.  no-unused-vars

🎯 规则配置建议

开发阶段配置

{
  "extends": ["next/core-web-vitals"],
  "rules": {
    "no-unused-vars": "warn",
    "react/display-name": "off",
    "@next/next/no-img-element": "warn",
    "react-hooks/exhaustive-deps": "warn"
  }
}

生产环境配置

{
  "extends": ["next/core-web-vitals"],
  "rules": {
    "no-unused-vars": "error",
    "@typescript-eslint/no-unused-vars": "error",
    "react/display-name": "error"
  }
}

🔄 自动修复

ESLint 提供了自动修复功能，但需要注意：

可自动修复的问题：

代码格式化
缺少分号
引号风格统一

需要手动修复的问题：

未使用的变量和导入
React Hooks 依赖问题
逻辑错误

使用自动修复：

pnpm run lint -- --fix

🚫 忽略构建时的 ESLint 检查

如果项目中有大量 ESLint 错误，可以在 next.config.mjs 中临时忽略：

const nextConfig = {
  eslint: {
    ignoreDuringBuilds: true,
  },
};

📝 最佳实践

渐进式修复：不要一次性修复所有问题，优先修复 error 级别的问题
团队规范：制定团队统一的 ESLint 规则配置
CI/CD 集成：在构建流程中集成 ESLint 检查
编辑器集成：确保所有团队成员的编辑器都正确配置了 ESLint

🎉 总结

通过本文的配置方案，我们成功解决了 Next.js 项目中 ESLint 配置的各种问题：

✅ 选择了稳定的 ESLint 8.x 版本
✅ 配置了简洁有效的规则
✅ 实现了 VS Code 的完美集成
✅ 提供了灵活的规则配置方案

希望这份指南能帮助你在 Next.js 项目中顺利配置 ESLint，提升代码质量和开发效率！

相关链接：

如果你觉得这篇文章对你有帮助，欢迎点赞收藏！有任何问题也欢迎在评论区讨论。