Next.js+TypeScript项目ESLint配置疑问及--fix失效排查

一、--fix未修复未使用变量的原因及解决方案 #

• 核心原因：@typescript-eslint/no-unused-vars（检测未使用变量的规则）默认不支持自动修复。ESLint无法判断你是暂时保留变量还是遗漏了使用场景，因此只会给出警告/错误提示，不会自动删除未使用的变量。
• 替代处理方式：
  1. 直接删除未使用的变量（最直接有效）；
  2. 若需暂时保留变量，可在变量前添加注释// eslint-disable-next-line @typescript-eslint/no-unused-vars忽略该规则；
• 额外排查点：
  • 确认脚本命令正确性：你的lint:fix命令next lint --fix符合Next.js规范，无需调整；
  • 检查.eslintignore文件，确保header.tsx未被排除在检查范围外；
  • 确认规则未被禁用：查看eslintrc.json中是否存在"@typescript-eslint/no-unused-vars": "off"，若有需删除该配置（plugin:@typescript-eslint/recommended已默认开启该规则为警告级别）。

二、Next.js + TypeScript ESLint基础标准配置优化 #

Next.js官方提供的eslint-config-next已整合React、TypeScript、Core Web Vitals等核心规则，无需重复引入多个extends，可简化配置避免规则冲突：

优化后的.eslintrc.json #

{
  "root": true,
  "extends": [
    "next/core-web-vitals",
    "plugin:@typescript-eslint/recommended",
    "plugin:prettier/recommended"
  ],
  "parser": "@typescript-eslint/parser",
  "parserOptions": {
    "ecmaVersion": "latest",
    "sourceType": "module"
  },
  "env": {
    "browser": true,
    "es2021": true,
    "node": true
  },
  "rules": {
    "@typescript-eslint/array-type": ["warn", {"default": "array"}],
    "@typescript-eslint/consistent-type-assertions": ["warn", {"assertionStyle": "as", "objectLiteralTypeAssertions": "never"}],
    "react/react-in-jsx-scope": "off",
    "react/prop-types": "off",
    "jsx-a11y/anchor-is-valid": "off"
  },
  "settings": {
    "react": {
      "version": "detect"
    }
  }
}

配置说明 #

• 精简extends：next/core-web-vitals已包含next、eslint:recommended、plugin:react/recommended、plugin:react-hooks/recommended的核心规则，无需重复引入；
• Prettier整合：plugin:prettier/recommended自动启用eslint-plugin-prettier和eslint-config-prettier，既让Prettier作为ESLint规则运行，又关闭ESLint中与Prettier冲突的规则；
• 移除冗余插件：extends中已包含的插件（如react、react-hooks、@typescript-eslint）无需在plugins字段重复声明，ESLint会自动加载；
• 规则精简：保留自定义必要规则，移除已被extends覆盖的重复规则（如react-hooks/rules-of-hooks已由next/core-web-vitals开启）。

三、VSCode ESLint插件使用指南 #

1. 确保VSCode已安装ESLint插件并启用；
2. 打开工作区设置（.vscode/settings.json），添加以下配置实现保存时自动修复：

{
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"]
}

3. 若插件不生效，可尝试重启VSCode或执行命令面板中的ESLint: Restart ESLint Server命令（按Ctrl+Shift+P打开命令面板搜索）。

四、额外建议 #

• 依赖精简：@typescript-eslint/eslint-plugin、@typescript-eslint/parser、eslint-plugin-react等依赖已被eslint-config-next间接依赖，可移至devDependencies中，或保持现状无需额外安装；
• 提交前检查：利用已安装的husky和lint-staged，配置提交代码前自动执行lint检查，避免不合格代码提交。在package.json中添加：

"lint-staged": {
  "*.{ts,tsx,js,jsx}": ["next lint --fix"]
}

然后执行husky add .husky/pre-commit "npx lint-staged"添加提交钩子。

内容的提问来源于stack exchange，提问作者program_bumble_bee