前端项目eslint配置选项详细解析

鹏多多2025-09-10 10:04

1. 前言

ESLint 是一款可高度配置的 JavaScript 代码检查工具，其核心价值在于帮助开发者在编码阶段主动发现并修复问题，而非等到运行时才暴露错误。它不仅能检测语法错误，还能规范代码风格、规避潜在逻辑风险，是现代前端 / Node.js 项目中保障代码质量的核心工具之一。

1.1 核心功能

ESLint 的核心能力围绕 "静态分析" 与 "灵活配置" 展开，主要包括：

  • 静态代码分析：无需运行代码，即可扫描出语法错误（如未定义变量）、逻辑漏洞（如条件中使用常量表达式）、风格不一致（如混用单双引号）等问题。
  • 自动修复支持：对格式错误（如缩进、分号）、简单风格问题（如引号转换）等，可通过 eslint --fix 命令自动修复，减少手动调整成本。
  • 规则可配置性：支持启用 / 禁用单个规则、调整规则严格级别，还可继承社区成熟配置（如 eslint:recommended），快速适配项目需求。

1.2 实际价值

在团队协作与工程化流程中，ESLint 的作用尤为突出：

  • 统一代码规范：消除因个人编码习惯差异导致的 "风格冲突"（如缩进用 2 空格还是 4 空格），让代码看起来像 "一个人写的"。
  • 降低错误风险：提前拦截低级错误（如未使用的变量、遗漏的分号），减少线上运行时故障。
  • 提升可维护性：规范的代码结构更易阅读、修改，降低新成员接入项目的学习成本。
  • 集成工程化流程：可嵌入 CI/CD 流水线（如 Jenkins、GitHub Actions），实现 "代码提交即检查"，阻止不规范代码合并入主分支。

2、错误级别

ESLint 为每条规则定义了 3 个严格级别，通过 "代号" 或 "别称" 配置，不同级别对应不同的检查行为，具体说明如下：

代号 别称 含义 描述
0 'off' 忽略 关闭规则
1 'warn' 警告 打开规则，并且将规则视为一个警告，检查通过
2 'error' 错误 打开规则，并且将规则视为一个错误 检查不通过，退出码为 1

注意：实际配置中，"代号" 与 "别称" 效果一致，可按需选择。例如 no-console: 0 与 no-console: 'off' 等价。

3、常用规则

ESLint 内置数百条规则，按功能可分为 "逻辑错误""最佳实践""变量声明" 等类别。以下整理项目中高频使用的规则，每条规则均标注 "作用"，帮助快速理解其价值。

规则详情可参考：ESLint 官方规则文档（比第三方链接更权威、更新及时）

3.1 逻辑错误类（规避代码运行风险）

此类规则用于拦截可能导致运行时错误或逻辑异常的代码，是保障代码 "正确性" 的核心：

objectivec 复制代码 
    no-cond-assign          // 禁止条件表达式中出现模棱两可的赋值操作符 
    no-console              // 禁用console 
    no-constant-condition   // 禁止在条件中使用常量表达式 
    no-debugger             // 禁用 debugger 
    no-dupe-args            // 禁止 function 定义中出现重名参数 
    no-dupe-keys            // 禁止对象字面量中出现重复的 key 
    no-duplicate-case       // 禁止出现重复的 case 标签 
    no-empty                // 禁止出现空语句块 
    no-ex-assign            // 禁止对 catch 子句的参数重新赋值 
    no-extra-boolean-cast   // 禁止不必要的布尔转换 
    no-extra-parens         // 禁止不必要的括号 
    no-extra-semi           // 禁止不必要的分号 
    no-func-assign          // 禁止对 function 声明重新赋值 
    no-inner-declarations   // 禁止在嵌套的块中出现变量声明或 function 声明 
    no-irregular-whitespace // 禁止在字符串和注释之外不规则的空白 
    no-obj-calls            // 禁止把全局对象作为函数调用 
    no-sparse-arrays        // 禁用稀疏数组 
    no-prototype-builtins   // 禁止直接使用Object.prototypes 的内置属性 
    no-unexpected-multiline // 禁止出现令人困惑的多行表达式 
    no-unreachable          // 禁止在return、throw、continue 和 break语句之后出现不可达代码 
    use-isnan               // 要求使用 isNaN() 检查 NaN 
    valid-typeof            // 强制 typeof 表达式与有效的字符串进行比较

3.2 最佳实践类（提升代码健壮性与可维护性）

此类规则不直接阻断运行，但遵循可减少潜在问题、提升代码可读性：

csharp 复制代码 
    array-callback-return   // 强制数组方法的回调函数中有 return 语句 
    block-scoped-var        // 强制把变量的使用限制在其定义的作用域范围内 
    complexity              // 指定程序中允许的最大环路复杂度 
    consistent-return       // 要求 return 语句要么总是指定返回的值，要么不指定 
    curly                   // 强制所有控制语句使用一致的括号风格 
    default-case            // 要求 switch 语句中有 default 分支 
    dot-location            // 强制在点号之前和之后一致的换行 
    dot-notation            // 强制在任何允许的时候使用点号 
    eqeqeq                  // 要求使用 === 和 !== 
    guard-for-in            // 要求 for-in 循环中有一个 if 语句 
    no-alert                // 禁用 alert、confirm 和 prompt 
    no-case-declarations    // 不允许在 case 子句中使用词法声明 
    no-else-return          // 禁止 if 语句中有 return 之后有 else 
    no-empty-function       // 禁止出现空函数 
    no-eq-null              // 禁止在没有类型检查操作符的情况下与 null 进行比较 
    no-eval                 // 禁用 eval() 
    no-extra-bind           // 禁止不必要的 .bind() 调用 
    no-fallthrough          // 禁止 case 语句落空 
    no-floating-decimal     // 禁止数字字面量中使用前导和末尾小数点 
    no-implicit-coercion    // 禁止使用短符号进行类型转换 
    no-implicit-globals     // 禁止在全局范围内使用 var 和命名的 function 声明 
    no-invalid-this         // 禁止 this 关键字出现在类和类对象之外 
    no-lone-blocks          // 禁用不必要的嵌套块 
    no-loop-func            // 禁止在循环中出现 function 声明和表达式 
    no-magic-numbers        // 禁用魔术数字 
    no-multi-spaces         // 禁止使用多个空格 
    no-multi-str            // 禁止使用多行字符串 
    no-new                  // 禁止在非赋值或条件语句中使用 new 操作符 
    no-new-func             // 禁止对 Function 对象使用 new 操作符 
    no-new-wrappers         // 禁止对 String，Number 和 Boolean 使用 new 操作符 
    no-param-reassign       // 不允许对 function 的参数进行重新赋值 
    no-redeclare            // 禁止使用 var 多次声明同一变量 
    no-return-assign        // 禁止在 return 语句中使用赋值语句 
    no-script-url           // 禁止使用 javascript: url 
    no-self-assign          // 禁止自我赋值 
    no-self-compare         // 禁止自身比较 
    no-sequences            // 禁用逗号操作符 
    no-unmodified-loop-condition   // 禁用一成不变的循环条件 
    no-unused-expressions   // 禁止出现未使用过的表达式 
    no-useless-call         // 禁止不必要的 .call() 和 .apply() 
    no-useless-concat       // 禁止不必要的字符串字面量或模板字面量的连接 
    vars-on-top             // 要求所有的 var 声明出现在它们所在的作用域顶部

3.3 变量声明类（规范变量定义与使用）

此类规则聚焦变量的声明、初始化与作用域，减少变量污染与未定义错误：

csharp 复制代码 
    init-declarations     // 要求或禁止 var 声明中的初始化 
    no-catch-shadow       // 不允许 catch 子句的参数与外层作用域中的变量同名 
    no-restricted-globals // 禁用特定的全局变量 
    no-shadow             // 禁止 var 声明 与外层作用域的变量同名 
    no-undef              // 禁用未声明的变量，除非它们在 /global / 注释中被提到 
    no-undef-init         // 禁止将变量初始化为 undefined 
    no-unused-vars        // 禁止出现未使用过的变量 
    no-use-before-define  // 不允许在变量定义之前使用它们

3.4 CommonJS 模块类（规范 Node.js 模块写法）

此类规则针对 Node.js 环境的 CommonJS 模块（require/module.exports），确保模块代码规范：

php 复制代码 
    global-require        // 要求 require() 出现在顶层模块作用域中 
    handle-callback-err   // 要求回调函数中有容错处理 
    no-mixed-requires     // 禁止混合常规 var 声明和 require 调用 
    no-new-require        // 禁止调用 require 时使用 new 操作符 
    no-path-concat        // 禁止对 dirname 和 filename进行字符串连接 
    no-restricted-modules // 禁用指定的通过 require 加载的模块

3.5 风格指南类（统一代码格式，提升可读性）

此类规则纯 "风格层面"，不影响代码功能，但统一后可减少团队协作中的 "格式争议"：

arduino 复制代码 
   array-bracket-spacing           // 强制数组方括号中使用一致的空格 
   block-spacing                   // 强制在单行代码块中使用一致的空格 
   brace-style                     // 强制在代码块中使用一致的大括号风格 
   camelcase                       // 强制使用骆驼拼写法命名约定 
   comma-spacing                   // 强制在逗号前后使用一致的空格 
   comma-style                     // 强制使用一致的逗号风格 
   computed-property-spacing       // 强制在计算的属性的方括号中使用一致的空格 
   eol-last                        // 强制文件末尾至少保留一行空行 
   func-names                      // 强制使用命名的 function 表达式 
   func-style                      // 强制一致地使用函数声明或函数表达式 
   indent                          // 强制使用一致的缩进 
   jsx-quotes                      // 强制在 JSX 属性中一致地使用双引号或单引号 
   key-spacing                     // 强制在对象字面量的属性中键和值之间使用一致的间距 
   keyword-spacing                 // 强制在关键字前后使用空格，比如if else 
   linebreak-style                 // 强制使用一致的换行风格 
   lines-around-comment            // 要求在注释周围有空行 
   max-depth                       // 强制可嵌套的块的最大深度 
   max-len                         // 强制一行的最大长度 
   max-lines                       // 强制最大行数 
   max-nested-callbacks            // 强制回调函数最大嵌套深度 
   max-params                      // 强制 function 定义中最多允许的参数数量 
   max-statements                  // 强制 function 块最多允许的的语句数量 
   max-statements-per-line         // 强制每一行中所允许的最大语句数量 
   new-cap                         // 要求构造函数首字母大写 
   new-parens                      // 要求调用无参构造函数时有圆括号 
   newline-after-var               // 要求或禁止 var 声明语句后有一行空行 
   newline-before-return           // 要求 return 语句之前有一空行 
   newline-per-chained-call        // 要求方法链中每个调用都有一个换行符 
   no-array-constructor            // 禁止使用 Array 构造函数 
   no-continue                     // 禁用 continue 语句 
   no-inline-comments              // 禁止在代码行后使用内联注释 
   no-lonely-if                    // 禁止 if 作为唯一的语句出现在 else 语句中 
   no-mixed-spaces-and-tabs        // 不允许空格和 tab 混合缩进 
   no-multiple-empty-lines         // 不允许多个空行 
   no-negated-condition            // 不允许否定的表达式 
   no-plusplus                     // 禁止使用一元操作符 ++ 和 -- 
   no-spaced-func                  // 禁止 function 标识符和括号之间出现空格 
   no-trailing-spaces              // 禁用行尾空格 
   no-whitespace-before-property   // 禁止属性前有空白 
   object-curly-newline            // 强制花括号内换行符的一致性 
   object-curly-spacing            // 强制在花括号中使用一致的空格 
   object-property-newline         // 强制将对象的属性放在不同的行上 
   one-var                         // 强制函数中的变量要么一起声明要么分开声明 
   one-var-declaration-per-line    // 要求或禁止在 var 声明周围换行 
   operator-assignment             // 要求或禁止在可能的情况下要求使用简化的赋值操作符 
   operator-linebreak              // 强制操作符使用一致的换行符 
   quote-props                     // 要求对象字面量属性名称用引号括起来 
   quotes                          // 强制使用一致的反勾号、双引号或单引号 
   require-jsdoc                   // 要求使用 JSDoc 注释 
   semi                            // 要求或禁止使用分号而不是 ASI 
   semi-spacing                    // 强制分号之前和之后使用一致的空格 
   sort-vars                       // 要求同一个声明块中的变量按顺序排列 
   space-before-blocks             // 强制在块之前使用一致的空格 
   space-before-function-paren     // 强制在 function的左括号之前使用一致的空格 
   space-in-parens                 // 强制在圆括号内使用一致的空格 
   space-infix-ops                 // 要求操作符周围有空格 
   space-unary-ops                 // 强制在一元操作符前后使用一致的空格 
   spaced-comment                  // 强制在注释中 // 或 /* 使用一致的空格
  • typeScript
java 复制代码 
@typescript-eslint/no-non-null-assertion // 是否禁止非空断言!

4. 项目实战：.eslintrc.js 配置解析

以下是适配 Vue 3 + TypeScript 项目的 ESLint 配置文件（/.eslintrc.js），结合项目实际需求调整规则，注释中已说明关键配置的目的与逻辑：

javascript 复制代码 
module.exports = {
	root: true,
	env: {
		browser: true,
		es2021: true,
		node: true
	},
	globals: {
		TAny: true,
		TDict: true,
		TFunc: true,
		TDialogButtonOption: true,
		THttpResponse: true,
		NodeJS: 'readonly',
		defineProps: 'readonly',
		defineEmits: 'readonly',
		defineExpose: 'readonly',
		withDefaults: 'readonly'
	},
	parser: 'vue-eslint-parser',
	parserOptions: {
		ecmaVersion: 12,
		parser: '@typescript-eslint/parser',
		sourceType: 'module'
	},
	extends: ['plugin:vue/vue3-essential', 'plugin:vue/essential', 'eslint:recommended'],
	plugins: ['vue', '@typescript-eslint'],
	rules: {
		'@type-eslint/ban-ts-ignore': 'off', // 配置禁用 @ts-ignore 注释
		'@type-eslint/explicit-function-return-type': 'off', // 要求函数和类方法上显式返回类型
		'@type-eslint/no-explicit-any': 'off', // 不允许any类型
		'@typescript-eslint/no-explicit-any': 'warn', // any不能乱用
		'@type-eslint/no-var-requires': 'off', // 禁止require语句，import语句除外
		'@type-eslint/no-empty-function': 'off', // 禁止空函数
		'@type-eslint/no-use-before-define': 'off', // 禁止在定义变量之前使用变量
		'@type-eslint/ban-ts-comment': 'off', // 禁止@ts-<指令>注释或要求指令后面有描述。
		'@type-eslint/ban-types': 'off', // 禁止某些类型
		'@type-eslint/no-non-null-assertion': 'off', // 不允许使用非空断言!后缀运算符
		'@type-eslint/explicit-module-boundary-types': 'off', // 对导出函数和类的公共类方法要求显式的返回和参数类型
		'vue/no-v-for-template-key': 0, // 不允许template上有key
		semi: ['error', 'never'], // 使用分号
		'comma-dangle': [
			// 语句后面是否使用逗号
			'error',
			{
				arrays: 'never',
				objects: 'never',
				imports: 'never',
				exports: 'never',
				functions: 'never'
			}
		],
		'vue/custom-event-name-casing': 'off', // 为自定义事件名强制执行特定的大小写
		'vue/attributes-order': 'off', // 强制属性的顺序
		'vue/one-component-per-file': 'off', // 强制每个组件应该在它自己的文件中
		'vue/html-closing-bracket-newline': 'off', // 要求或禁止在标记的右括号前换行
		'vue/max-attributes-per-line': 'off', // 强制规定每行的最大属性数
		'vue/multiline-html-element-content-newline': 'off', // 要求在多行元素的内容之前和之后使用换行符
		'vue/singleline-html-element-content-newline': 'off', // 要求在单行元素的内容前后使用换行符
		'vue/attribute-hyphenation': 'off', // 对模板中的自定义组件强制实施属性命名样式
		'vue/html-self-closing': 'off', // 强制实施自动关闭样式
		'vue/no-multiple-template-root': 'off', // template中只允许模板里存在一个根节点
		'vue/require-default-prop': 'off', // props需要默认值
		'vue/no-v-model-argument': 'off', // 检查自定义组件上是否没有参数
		'vue/no-arrow-functions-in-watch': 'off', // 禁止使用箭头函数定义watch
		'vue/no-template-key': 'off', // 不允许template上有key
		'vue/no-v-html': 'off', // 禁止使用 V-HTML 来防止 XSS 攻击
		'vue/comment-directive': 'off', // 支持注释指令
		'vue/no-parsing-error': 'off', // 报告语法错误
		'vue/no-deprecated-v-on-native-modifier': 'off', // 弃用修饰符 ondirective @xxx.native
		'vue/multi-word-component-names': 'off', // 组件名称始终是多字的
		'no-useless-escape': 'off', // 禁用不必要的转义
		'no-sparse-arrays': 'off', // 禁用稀疏数组
		'no-prototype-builtins': 'off', // 禁止直接使用Object.prototypes 的内置属性
		'no-constant-condition': 'off', // 禁止在条件中使用常量表达式
		'no-use-before-define': 'off', // 不允许在变量定义之前使用它们
		'no-restricted-globals': 'off', // 禁用特定的全局变量
		'no-restricted-syntax': 'off', // 禁止使用特定的语法
		'generator-star-spacing': 'off', // 强制 generator 函数中 * 号周围有空格
		'no-unreachable': 'off', // 禁止在return、throw、continue 和 break语句之后出现不可达代码
		'no-unused-vars': ['error', { varsIgnorePattern: '.*', args: 'none' }], // 禁止出现未使用过的变量
		'no-case-declarations': 'off', // 不允许在 case 子句中使用词法声明
		'no-console': 'off', // 禁用console
		'arrow-parens': 'off', // 箭头函数一个参数可以不要括号
		'no-eq-null': 2, // 禁止对null使用==或!=运算符
		quotes: [1, 'single'], // 引号类型
		'prefer-const': 0, // 首选const
		eqeqeq: 2, // 必须使用全等
		'default-case': 2, // switch语句最后必须有default
		'no-var': 0, // 禁用var，用let和const代替
		'no-trailing-spaces': 1 // 一行结束后面不要有空格
	}
}

本次分享就到这儿啦，我是鹏多多，如果看了觉得有帮助的，欢迎 点赞 关注 评论，在此谢过道友；

往期文章

相关推荐
然我3 小时前
面试官：这道 Promise 输出题你都错？别再踩 pending 和状态凝固的坑了！（附超全解析）
前端·javascript·面试
bug_kada4 小时前
让你彻底明白什么是闭包（附常见坑点）
前端·javascript
吴楷鹏4 小时前
TypeScript 为什么要增加一个 satisfies？
前端·typescript
光影少年4 小时前
js异步解决方案以及实现原理
前端·javascript·掘金·金石计划
阿隆_趣编程4 小时前
为了方便相亲，我用AI写了一款小程序
前端·javascript·微信小程序
EndingCoder4 小时前
Electron 跨平台兼容性：处理 OS 差异
前端·javascript·electron·前端框架·node.js·chrome devtools
秋田君4 小时前
Vue3+Node.js 实现大文件上传：断点续传、秒传、分片上传完整教程（含源码）
前端
爱隐身的官人4 小时前
ctfshow - web - nodejs
前端·nodejs·ctf
zhong liu bin4 小时前
Vue框架技术详解——项目驱动概念理解【前端】【Vue】
前端·javascript·vue.js·vscode·vue
热门推荐
01UV安装并设置国内源02A股预测还能更准？开源大模型Kronos带你跑通预测+回测全流程032025 年高教社杯全国大学生数学建模竞赛C 题 NIPT 的时点选择与胎儿的异常判定 完整成品思路模型代码分享，全网首发高质量！！！042025年数学建模国赛C题超详细解题思路05UV 工具安装与国内镜像源配置指南06不再让Windows更新！&Edge游戏助手卸载及关闭自动更新07KGG转MP3工具|非KGM文件|解密音频08Linux下V2Ray安装配置指南09突破百度网盘的下载限速，两种方法教会你【超详细】10教你如何认证 Gemini 教育优惠的二次验证，薅个 1年的 Gemini Pro 会员