ESLint 配置文件 (.eslintrc.js) 完整指南

ESLint 是 JavaScript 和 TypeScript 的静态代码分析工具，用于识别和报告代码中的问题。以下是 .eslintrc.js 配置文件的完整指南。

基本配置文件结构

module.exports = {
  // 配置基础
  env: {
    // 环境配置
  },
  extends: [
    // 扩展配置
  ],
  parser: "", // 解析器配置
  parserOptions: {
    // 解析器选项
  },
  plugins: [
    // 插件列表
  ],
  rules: {
    // 规则配置
  },
  globals: {
    // 全局变量
  },
  overrides: [
    // 文件覆盖配置
  ],
  settings: {
    // 共享设置
  }
};

完整配置示例

module.exports = {
  // 指定 ESLint 的解析器
  parser: "@typescript-eslint/parser",
  
  // 指定解析器选项
  parserOptions: {
    ecmaVersion: 2020, // 使用的 ECMAScript 版本
    sourceType: "module", // 模块类型: "script" 或 "module"
    ecmaFeatures: {
      jsx: true, // 启用 JSX
      impliedStrict: true, // 启用严格模式
      experimentalObjectRestSpread: true
    },
    project: "./tsconfig.json", // TypeScript 配置（如使用 TypeScript）
    tsconfigRootDir: __dirname,
  },
  
  // 指定代码运行的环境
  env: {
    browser: true,    // 浏览器全局变量
    node: true,       // Node.js 全局变量
    es6: true,        // 启用 ES6 特性
    jest: true,       // Jest 测试框架
    mocha: true       // Mocha 测试框架
  },
  
  // 扩展共享配置
  extends: [
    "eslint:recommended",           // ESLint 推荐规则
    "plugin:react/recommended",     // React 推荐规则
    "plugin:@typescript-eslint/recommended", // TypeScript 推荐规则
    "plugin:prettier/recommended",  // Prettier 集成
    "airbnb",                       // Airbnb 风格指南
    "airbnb/hooks"                  // React Hooks 规则
  ],
  
  // 使用的插件
  plugins: [
    "react",           // React 插件
    "react-hooks",     // React Hooks 插件
    "@typescript-eslint", // TypeScript 插件
    "import",          // ES6 import/export 语法检查
    "jsx-a11y",        // 可访问性检查
    "prettier"         // Prettier 格式化
  ],
  
  // 自定义规则
  rules: {
    // 错误级别：0 = off, 1 = warn, 2 = error
    
    // 基本规则
    "no-console": process.env.NODE_ENV === "production" ? "warn" : "off",
    "no-debugger": process.env.NODE_ENV === "production" ? "error" : "off",
    "no-unused-vars": "warn",
    "no-undef": "error",
    
    // 代码风格
    "indent": ["error", 2], // 2 空格缩进
    "quotes": ["error", "single"], // 单引号
    "semi": ["error", "always"], // 分号
    "comma-dangle": ["error", "always-multiline"], // 尾随逗号
    
    // React 相关
    "react/prop-types": "off", // 使用 TypeScript 时关闭
    "react/react-in-jsx-scope": "off", // React 17+ 不需要导入 React
    "react/jsx-filename-extension": [1, { "extensions": [".js", ".jsx", ".tsx"] }],
    
    // TypeScript 相关
    "@typescript-eslint/explicit-function-return-type": "off",
    "@typescript-eslint/no-explicit-any": "warn",
    
    // Import 相关
    "import/extensions": "off",
    "import/prefer-default-export": "off",
    
    // Prettier 集成
    "prettier/prettier": "error"
  },
  
  // 全局变量
  globals: {
    React: "writable",
    process: "readonly",
    __dirname: "readonly",
    __filename: "readonly"
  },
  
  // 文件特定配置
  overrides: [
    {
      // TypeScript 文件
      files: ["**/*.ts", "**/*.tsx"],
      parser: "@typescript-eslint/parser",
      extends: [
        "plugin:@typescript-eslint/recommended"
      ],
      rules: {
        "@typescript-eslint/no-unused-vars": "error"
      }
    },
    {
      // 测试文件
      files: ["**/__tests__/**/*", "**/*.{test,spec}.*"],
      env: {
        jest: true
      },
      rules: {
        "no-console": "off"
      }
    },
    {
      // 配置文件
      files: [".eslintrc.js", "webpack.config.js"],
      env: {
        node: true
      },
      rules: {
        "@typescript-eslint/no-var-requires": "off"
      }
    }
  ],
  
  // 共享设置
  settings: {
    react: {
      version: "detect" // 自动检测 React 版本
    },
    "import/resolver": {
      node: {
        extensions: [".js", ".jsx", ".ts", ".tsx"],
        paths: ["src"]
      },
      typescript: {
        alwaysTryTypes: true
      }
    }
  }
};

常用配置组合

React 项目配置

module.exports = {
  env: {
    browser: true,
    es6: true,
  },
  extends: [
    "eslint:recommended",
    "plugin:react/recommended",
    "plugin:react-hooks/recommended",
    "plugin:jsx-a11y/recommended",
  ],
  plugins: ["react", "react-hooks", "jsx-a11y"],
  parserOptions: {
    ecmaVersion: 2020,
    sourceType: "module",
    ecmaFeatures: {
      jsx: true,
    },
  },
  rules: {
    "react/prop-types": "off",
    "react/react-in-jsx-scope": "off",
    "react-hooks/rules-of-hooks": "error",
    "react-hooks/exhaustive-deps": "warn",
  },
  settings: {
    react: {
      version: "detect",
    },
  },
};

TypeScript 项目配置

module.exports = {
  parser: "@typescript-eslint/parser",
  parserOptions: {
    ecmaVersion: 2020,
    sourceType: "module",
    project: "./tsconfig.json",
  },
  extends: [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:@typescript-eslint/recommended-requiring-type-checking",
  ],
  plugins: ["@typescript-eslint"],
  rules: {
    "@typescript-eslint/explicit-module-boundary-types": "off",
    "@typescript-eslint/no-unused-vars": "error",
    "@typescript-eslint/no-explicit-any": "warn",
  },
};

Node.js 项目配置

module.exports = {
  env: {
    node: true,
    es6: true,
  },
  extends: ["eslint:recommended", "airbnb-base"],
  parserOptions: {
    ecmaVersion: 2020,
  },
  rules: {
    "no-console": "off",
    "import/no-unresolved": "error",
    "consistent-return": "off",
  },
};

Vue.js 项目配置

module.exports = {
  env: {
    browser: true,
    es6: true,
  },
  extends: [
    "eslint:recommended",
    "plugin:vue/vue3-essential",
    "@vue/typescript/recommended",
  ],
  parser: "vue-eslint-parser",
  parserOptions: {
    parser: "@typescript-eslint/parser",
    ecmaVersion: 2020,
    sourceType: "module",
  },
  plugins: ["vue"],
  rules: {
    "vue/multi-word-component-names": "off",
    "@typescript-eslint/no-explicit-any": "off",
  },
};

常用规则分类

错误预防规则

rules: {
  // 禁止使用 console
  "no-console": process.env.NODE_ENV === "production" ? "warn" : "off",
  
  // 禁止使用 debugger
  "no-debugger": process.env.NODE_ENV === "production" ? "error" : "off",
  
  // 禁止未使用的变量
  "no-unused-vars": ["error", { "args": "none" }],
  
  // 禁止未声明的变量
  "no-undef": "error",
  
  // 禁止重复导入
  "no-duplicate-imports": "error",
  
  // 禁止在条件中使用赋值语句
  "no-cond-assign": "error",
}

代码风格规则

rules: {
  // 缩进
  "indent": ["error", 2, { "SwitchCase": 1 }],
  
  // 引号
  "quotes": ["error", "single", { "avoidEscape": true }],
  
  // 分号
  "semi": ["error", "always"],
  
  // 逗号风格
  "comma-dangle": ["error", "always-multiline"],
  
  // 对象字面量花括号风格
  "object-curly-spacing": ["error", "always"],
  
  // 数组括号风格
  "array-bracket-spacing": ["error", "never"],
}

最佳实践规则

rules: {
  // 使用 === 和 !==
  "eqeqeq": ["error", "always"],
  
  // 强制使用驼峰命名
  "camelcase": ["error", { "properties": "never" }],
  
  // 箭头函数括号
  "arrow-parens": ["error", "as-needed"],
  
  // 优先使用 const
  "prefer-const": "error",
  
  // 模板字符串
  "prefer-template": "error",
}

与 Prettier 集成

module.exports = {
  extends: [
    "eslint:recommended",
    "plugin:prettier/recommended" // 必须放在最后
  ],
  rules: {
    "prettier/prettier": "error"
  }
};

需要安装：

npm install --save-dev eslint-config-prettier eslint-plugin-prettier

环境特定配置

开发环境配置

// .eslintrc.dev.js
module.exports = {
  rules: {
    "no-console": "off",
    "no-debugger": "off",
    "no-unused-vars": "warn"
  }
};

生产环境配置

// .eslintrc.prod.js
module.exports = {
  rules: {
    "no-console": "error",
    "no-debugger": "error",
    "no-alert": "error"
  }
};

忽略文件配置 (.eslintignore)

# 依赖目录
node_modules/
dist/
build/

# 配置文件
*.config.js

# 日志文件
*.log

# 环境文件
.env
.env.local

# IDE 文件
.vscode/
.idea/

# 操作系统文件
.DS_Store
Thumbs.db

包管理器脚本配置

在 package.json 中添加：

{
  "scripts": {
    "lint": "eslint . --ext .js,.jsx,.ts,.tsx",
    "lint:fix": "eslint . --ext .js,.jsx,.ts,.tsx --fix",
    "lint:watch": "eslint . --ext .js,.jsx,.ts,.tsx --watch"
  }
}

这个完整的 ESLint 配置指南应该能帮助你为任何类型的 JavaScript/TypeScript 项目设置合适的代码检查规则。根据你的具体需求调整配置即可。