知识库

Appearance

Return to top
On this page

ESLint 规则详解

ESLint 的规则是代码检查的核心，本章将详细介绍各种类型的规则及其配置方法。

规则分类

1. 问题检测规则（Possible Errors）

这些规则旨在帮助发现代码中的潜在错误：

javascript
module.exports = {
  rules: {
    // 禁止使用 console
    'no-console': 'warn',
    
    // 禁止使用 debugger
    'no-debugger': 'error',
    
    // 禁止未定义变量
    'no-undef': 'error',
    
    // 禁止不必要的括号
    'no-extra-parens': ['error', 'all', {
      'conditionalAssign': true,
      'nestedBinaryExpressions': false,
      'returnAssign': false,
      'enforceForArrowConditionals': false
    }],
    
    // 禁止不必要地转义字符
    'no-useless-escape': 'error',
    
    // 要求使用 isNaN() 检查 NaN
    'use-isnan': 'error',
    
    // 强制比较时使用 NaN
    'no-self-compare': 'error',
    
    // 禁止不必要的 catch 子句
    'no-useless-catch': 'error',
    
    // 要求所有的浮点数都必须有一个数字在至少一个小数点之前或之后
    'no-floating-decimal': 'error',
    
    // 禁止在常规字符串中出现模板字面量占位符语法
    'no-template-curly-in-string': 'error'
  }
};

2. 最佳实践规则（Best Practices）

这些规则帮助您编写更好的代码：

javascript
module.exports = {
  rules: {
    // 要求使用 === 和 !==
    'eqeqeq': ['error', 'always', {
      'null': 'ignore'  // 可以忽略 null 比较
    }],
    
    // 禁止 case 语句落空
    'no-fallthrough': 'error',
    
    // 禁止使用 alert, confirm, prompt
    'no-alert': 'warn',
    
    // 禁止使用 caller 或 callee
    'no-caller': 'error',
    
    // 要求使用骆驼拼写法
    'camelcase': ['error', {
      'properties': 'never',  // 属性名可以不是驼峰
      'ignoreDestructuring': false
    }],
    
    // 禁止删除变量
    'no-delete-var': 'error',
    
    // 禁止标签与变量同名
    'no-label-var': 'error',
    
    // 禁止混合普通变量声明和解构
    'no-var': 'error',  // 优先使用 let 或 const
    
    // 要求尽可能使用 const
    'prefer-const': 'error',
    
    // 禁止在条件语句中赋值
    'no-cond-assign': ['error', 'always'],
    
    // 要求 return 语句要么总是指定值，要么不指定值
    'consistent-return': 'error'
  }
};

3. 变量处理规则（Variables）

这些规则帮助处理变量：

javascript
module.exports = {
  rules: {
    // 禁止删除变量
    'no-delete-var': 'error',
    
    // 禁止标签与变量同名
    'no-label-var': 'error',
    
    // 禁止使用特殊块作用域的变量
    'no-shadow': 'error',
    
    // 禁止初始化变量为 undefined
    'no-undef-init': 'error',
    
    // 禁止使用未使用的变量
    'no-unused-vars': ['error', {
      'vars': 'all',
      'args': 'after-used',
      'ignoreRestSiblings': true,
      'argsIgnorePattern': '^_'
    }],
    
    // 禁止在变量定义之前使用
    'no-use-before-define': ['error', {
      'functions': true,
      'classes': true,
      'variables': true
    }],
    
    // 禁止未声明的变量
    'no-implicit-globals': 'error'
  }
};

4. 风格指南规则（Stylistic Issues）

这些规则与代码风格有关：

javascript
module.exports = {
  rules: {
    // 要求使用一致的缩进
    'indent': ['error', 2, {
      'SwitchCase': 1,
      'VariableDeclarator': 1,
      'outerIIFEBody': 1,
      'MemberExpression': 1,
      'FunctionDeclaration': {'parameters': 1, 'body': 1},
      'FunctionExpression': {'parameters': 1, 'body': 1},
      'CallExpression': {'arguments': 1},
      'ArrayExpression': 1,
      'ObjectExpression': 1,
      'ImportDeclaration': 1,
      'flatTernaryExpressions': false,
      'ignoreComments': false
    }],
    
    // 要求使用一致的换行符
    'linebreak-style': ['error', 'unix'],
    
    // 要求使用一致的引号
    'quotes': ['error', 'single', {
      'avoidEscape': true,
      'allowTemplateLiterals': false
    }],
    
    // 要求使用分号
    'semi': ['error', 'always'],
    
    // 要求在块之前有一致的空格
    'space-before-blocks': ['error', 'always'],
    
    // 要求在关键字前后有空格
    'keyword-spacing': ['error', {
      'before': true,
      'after': true,
      'overrides': {
        'return': {'after': true},
        'throw': {'after': true},
        'case': {'after': true}
      }
    }],
    
    // 强制一行的最大长度
    'max-len': ['error', {
      'code': 120,
      'tabWidth': 2,
      'comments': 120,
      'ignoreComments': false,
      'ignoreTrailingComments': true,
      'ignoreUrls': true,
      'ignoreStrings': true,
      'ignoreTemplateLiterals': true,
      'ignoreRegExpLiterals': true
    }],
    
    // 要求方法链中每个调用都有一个换行符
    'newline-per-chained-call': ['error', {'ignoreChainWithDepth': 3}],
    
    // 要求对象属性在不同行上
    'object-property-newline': ['error', {
      'allowAllPropertiesOnSameLine': true
    }]
  }
};

规则配置语法详解

规则严重程度

javascript
module.exports = {
  rules: {
    // 使用字符串形式
    'no-console': 'off',     // 关闭规则
    'no-console': 'warn',    // 警告级别
    'no-console': 'error',   // 错误级别
    
    // 使用数字形式
    'no-debugger': 0,        // 关闭规则
    'no-debugger': 1,        // 警告级别
    'no-debugger': 2,        // 错误级别
    
    // 使用数组形式（带选项）
    'semi': ['error', 'always'],
    'quotes': ['warn', 'single', { 'avoidEscape': true }]
  }
};

规则选项详解

javascript
module.exports = {
  rules: {
    // 基本选项
    'no-var': 'error',
    
    // 单个选项
    'semi': ['error', 'always'],
    
    // 多个选项
    'max-len': ['error', {
      'code': 120,
      'ignoreComments': true,
      'ignoreUrls': true
    }],
    
    // 数组和对象混合选项
    'array-bracket-spacing': ['error', 'never', {
      'singleValue': true,
      'objectsInArrays': false,
      'arraysInArrays': false
    }],
    
    // 多级配置
    'brace-style': ['error', '1tbs', {
      'allowSingleLine': true
    }]
  }
};

常用规则详解

1. 代码格式规则

javascript
module.exports = {
  rules: {
    // 逗号风格
    'comma-style': ['error', 'last'],
    
    // 逗号间距
    'comma-spacing': ['error', {'before': false, 'after': true}],
    
    // 分号间距
    'semi-spacing': ['error', {'before': false, 'after': true}],
    
    // 分号位置
    'semi-style': ['error', 'last'],
    
    // 块内空行
    'padded-blocks': ['error', 'never'],
    
    // 空行规则
    'lines-between-class-members': ['error', 'always', {
      'exceptAfterSingleLine': true
    }],
    
    // 空行要求
    'padding-line-between-statements': [
      'error',
      { 'blankLine': 'always', 'prev': '*', 'next': 'return' },
      { 'blankLine': 'always', 'prev': ['const', 'let', 'var'], 'next': '*' },
      { 'blankLine': 'any', 'prev': ['const', 'let', 'var'], 'next': ['const', 'let', 'var'] }
    ]
  }
};

2. 命名约定规则

javascript
module.exports = {
  rules: {
    // 变量命名
    'camelcase': ['error', {
      'properties': 'never',
      'ignoreDestructuring': false,
      'ignoreImports': true,
      'ignoreGlobals': true
    }],
    
    // 常量命名
    'constant-case': ['error', {
      'properties': 'always'
    }],
    
    // 函数命名
    'func-name-matching': ['error', 'always', {
      'includeCommonJSModuleExports': false
    }],
    
    // 命名规则
    'id-match': ['error', '^[a-zA-Z_$][a-zA-Z0-9_$]*$', {
      'properties': false,
      'onlyDeclarations': true,
      'ignoreDestructuring': false
    }]
  }
};

3. 对象和数组规则

javascript
module.exports = {
  rules: {
    // 对象属性新行
    'object-curly-newline': ['error', {
      'ObjectExpression': {'minProperties': 4, 'multiline': true, 'consistent': true},
      'ObjectPattern': {'minProperties': 4, 'multiline': true, 'consistent': true},
      'ExportDeclaration': {'minProperties': 4, 'multiline': true, 'consistent': true}
    }],
    
    // 对象花括号间距
    'object-curly-spacing': ['error', 'always'],
    
    // 对象属性引号
    'quote-props': ['error', 'as-needed', {
      'keywords': false,
      'unnecessary': true,
      'numbers': false
    }],
    
    // 数组括号间距
    'array-bracket-spacing': ['error', 'never'],
    
    // 数组括号新行
    'array-bracket-newline': ['error', 'consistent'],
    
    // 尾随逗号
    'comma-dangle': ['error', {
      'arrays': 'never',
      'objects': 'never',
      'imports': 'never',
      'exports': 'never',
      'functions': 'never'
    }]
  }
};

React 特定规则

javascript
module.exports = {
  plugins: ['react'],
  rules: {
    // React 版本检测
    'react/react-in-jsx-scope': 'error',
    
    // JSX 标签闭合
    'react/self-closing-comp': 'error',
    
    // JSX 间距
    'react/jsx-tag-spacing': ['error', {
      'closingSlash': 'never',
      'beforeSelfClosing': 'always',
      'afterOpening': 'never',
      'beforeClosing': 'never'
    }],
    
    // JSX 闭合括号位置
    'react/jsx-closing-bracket-location': ['error', 'line-aligned'],
    
    // JSX 最大 props 数量
    'react/jsx-max-props-per-line': ['error', {'maximum': 1, 'when': 'multiline'}],
    
    // JSX 新行
    'react/jsx-first-prop-new-line': ['error', 'multiline-multiprop'],
    
    // PropTypes 定义
    'react/prop-types': ['error', {
      'ignore': [],
      'customValidators': [],
      'skipUndeclared': false
    }],
    
    // 组件定义
    'react/display-name': 'error'
  }
};

TypeScript 特定规则

javascript
module.exports = {
  plugins: ['@typescript-eslint'],
  rules: {
    // 显式函数返回类型
    '@typescript-eslint/explicit-function-return-type': ['error', {
      'allowExpressions': true,
      'allowTypedFunctionExpressions': true,
      'allowHigherOrderFunctions': true,
      'allowDirectConstAssertionInArrowFunctions': true,
      'allowConciseArrowFunctionExpressionsStartingWithVoid': false
    }],
    
    // 显式成员访问
    '@typescript-eslint/explicit-member-accessibility': ['error', {
      'accessibility': 'explicit'
    }],
    
    // 命名约定
    '@typescript-eslint/naming-convention': [
      'error',
      {
        'selector': 'variableLike',
        'format': ['camelCase', 'UPPER_CASE']
      },
      {
        'selector': 'typeLike',
        'format': ['PascalCase']
      }
    ],
    
    // 不允许 any
    '@typescript-eslint/no-explicit-any': 'warn',
    
    // 不允许空函数
    '@typescript-eslint/no-empty-function': 'error',
    
    // 不允许空接口
    '@typescript-eslint/no-empty-interface': 'error',
    
    // 不允许不安全的任意类型
    '@typescript-eslint/no-unsafe-assignment': 'error'
  }
};

自定义规则

创建自定义规则

javascript
// 自定义规则示例
module.exports = {
  rules: {
    // 自定义规则配置
    'my-custom-rule': ['error', {
      'option1': 'value1',
      'option2': 'value2'
    }]
  }
};

使用插件规则

javascript
module.exports = {
  plugins: [
    'import',
    'jsx-a11y'
  ],
  rules: {
    // Import 规则
    'import/order': ['error', {
      'groups': ['builtin', 'external', 'internal', 'parent', 'sibling', 'index'],
      'newlines-between': 'always',
      'alphabetize': {
        'order': 'asc',
        'caseInsensitive': true
      }
    }],
    
    // Accessibility 规则
    'jsx-a11y/alt-text': 'error',
    'jsx-a11y/anchor-has-content': 'error',
    'jsx-a11y/click-events-have-key-events': 'error',
    'jsx-a11y/no-static-element-interactions': 'error'
  }
};

规则性能考虑

性能优化规则

javascript
module.exports = {
  rules: {
    // 对性能影响较小的规则
    'no-console': 'warn',
    'semi': 'error',
    'quotes': 'error',
    
    // 对性能影响较大的规则（谨慎使用）
    'no-unused-vars': 'warn',  // 检查所有变量使用情况
    'complexity': ['warn', 10],  // 圈复杂度检查
    'max-depth': ['warn', 4]    // 嵌套深度检查
  },
  
  // 使用 overrides 为不同文件类型设置不同规则
  overrides: [
    {
      files: ['*.test.js', '*.spec.js'],
      rules: {
        'no-unused-vars': 'off',  // 测试文件中可适当放宽规则
        'max-nested-callbacks': 'off'
      }
    }
  ]
};

小结

ESLint 规则是代码检查的核心，通过合理配置各种规则，可以有效地保证代码质量和一致性。不同类型的规则有不同的用途，需要根据项目需求进行选择和配置。下一章我们将介绍 ESLint 的插件系统。