目录
前言
本文是给用 vite 创建的 vue3 项目配置 ESLint,在配置 ESLint 之前建议:
- 先配置好 vite.config.ts
- 再配置好 tsconfig.json 。
- 由于 vetur 完全支持了 prettier 的格式化风格,所以 vue 提倡使用 prettier 而不是 eslint 来格式化代码。为了解决 eslint 规则和 prettier 规则的冲突,就要用到 eslint-config-prettier 依赖包。
- 使用 eslint-config-prettier 禁用所有与格式化相关的 ESLint 规则后,需要在根目录下新建 prettier 的配置文件,本文创建的是 prettier.config.js 文件。在 .eslintrc.js 文件的 extends 中,通过
plugin:prettier/recommended
属性,将 prettier.config.js 文件中的配置合并到 .eslintrc.js 文件中。需要注意的是,plugin:prettier/recommended
必须作为你的最后一个扩展。 - 在 vite 配置文件中,同一属性下,后引入的规则会覆盖前面的规则。
一、下载安装相关的依赖包
综合分析普遍使用的 eslint 依赖包后,推荐下面这一整套依赖包:
推荐必配 9 个依赖包:
- eslint:
- ESLint 是一种用于识别和报告在 ECMAScript/JavaScript 代码中发现的模式的工具。
- 必须首先安装这个依赖包,因为其他的依赖包建立在它之上。
- eslint-define-config:为 .eslintrc.js 文件提供
defineConfig
功能。 - eslint-plugin-vue:Vue.js 的官方 ESLint 插件,它允许我们使用 ESLint 检查文件中的 Vue 代码。
- eslint-plugin-prettier:
- 将 Prettier 作为 ESLint 规则运行。
- 如果你想禁用与代码格式相关的所有其他 ESLint 规则,并且仅启用检测潜在错误的规则,则此插件效果最佳。
- 如果你安装了 eslint 那么你应该会遇到 eslint 规则和 prettier 规则冲突。可用 eslint-config-prettier 解决 eslint 规则和 prettier 规则的冲突。
- eslint-config-prettier:关闭所有不必要或可能与 Prettier 冲突的规则。
- vue-eslint-parser:文件的 ESLint 自定义解析器.vue。
- @typescript-eslint/parser:一个 ESLint 解析器,它利用TypeScript ESTree允许 ESLint 对 TypeScript 源代码进行 lint。
- @typescript-eslint/eslint-plugin:一个为 TypeScript 代码库提供 lint 规则的 ESLint 插件。
- prettier:
推荐可选 2 个依赖包:
- eslint-plugin-import:支持 ES2015+ (ES6+)
import / export
语法的规则,并防止文件路径和导入名称拼写错误的问题。 - eslint-config-airbnb-base:
- 这个包提供了 Airbnb 的基本 JS .eslintrc(没有 React 插件)作为可扩展的共享配置。
- 安装 eslint-config-airbnb-base 之前请先安装 eslint-plugin-import。
因为只有开发阶段需要 eslint,所以将 eslint 的这些依赖添加到开发阶段的依赖 devDependencies
中即可。
// 2 个
npm i -D eslint eslint-define-config
// 2 个
npm i -D eslint-plugin-vue vue-eslint-parser
// 3 个
npm i -D prettier eslint-plugin-prettier eslint-config-prettier
// 2 个
npm i -D @typescript-eslint/parser @typescript-eslint/eslint-plugin
二、配置 .eslintrc.js
使用基于 eslint-define-config
依赖的 defineConfig
方法来配置 .eslintrc.js
。
defineConfig
方法里的基本成员:
- root:是否开启 eslint。
- env:配置编译器宏环境。
- parser:
eslint-plugin-vue
依赖包规定了parser
项的设定,详情请移步:如何使用自定义解析器?。 - parserOptions:若使用
@typescript-eslint/parser
依赖包作为自定义的解析器,需要配置parserOptions
属性来设置解析器选项。其详细配置下面会讲。 - extends:在此处添加更多通用规则集。
- rules:在此处 覆盖 或 添加 规则设置。
1、重点成员解析
(1)、parserOptions
parserOptions
用来配置解析器选项。
parserOptions
可用的选项有:
- parser:可选的。自定义解析器。比如:@babel/eslint-parser或 @typescript-eslint/parser
- ecmaVersion:
- 可设为 3、5(默认)、6……指定要使用的 ECMAScript 语法版本。
- 可设为 2015(同6)、2016(同7)、2017(同8)……基于年份的命名。
- 可设为 “latest”,以使用最新支持的版本。
- sourceType:默认是 “script”。当代码在 ECMAScript 模块中时其值需设为 “module”。
- allowReserved:可选的。布尔值。如果 ecmaVersion 是 3,就允许使用保留字作为标识符,否则不允许。
- ecmaFeatures:可选的。一个对象,指示您想使用哪些附加语言功能:
- globalReturn:允许 return 全局范围内的语句。
- impliedStrict:布尔值。如果 ecmaVersion 是 5 或更大,就启用全局严格模式,否则无需启用。
- jsx:是否启用 JSX。
2、.eslintrc.js 配置案例
const { defineConfig } = require('eslint-define-config')
module.exports = defineConfig({
root: true,
env: { // 环境
browser: true, // 浏览器环境中的全局变量。
node: true, // Node.js 全局变量和 Node.js 作用域。
es6: true // 启用除了 modules 以外的所有 ECMAScript 6 特性(该选项会自动设置 ecmaVersion 解析器选项为 6)。
},
parser: 'vue-eslint-parser', // 解析器
parserOptions: { // 解析器配置
parser: '@typescript-eslint/parser', // 解析器
ecmaVersion: 'latest', // 5(默认), 你可以使用 6、7、8、9 或 10 来指定你想要使用的 ECMAScript 版本。你也可以用年份命名的版本号,你也可以用 latest 来指向最新的版本。
sourceType: 'module', // 设置为 "script" (默认) 或 "module"(如果你的代码是 ECMAScript 模块)。
jsxPragma: 'React', // 支持 ReactJSX 语法
ecmaFeatures: { // 表示你想使用的额外的语言特性
jsx: true // 启用 JSX
}
},
extends: [
'plugin:vue/vue3-recommended',
'plugin:@typescript-eslint/recommended',
'prettier',
'plugin:prettier/recommended' // 一定要放在最后。因为 extends 中后引入的规则会覆盖前面的规则。
],
rules: {
// @typescript-eslint
'@typescript-eslint/explicit-function-return-type': 'off', // 需要函数和类方法的显式返回类型
'@typescript-eslint/no-explicit-any': 'off', // 禁止使用该 any 类型
'@typescript-eslint/no-var-requires': 'off', // 不允许使用 require 语句,除了在 import 语句中
'@typescript-eslint/no-empty-function': 'off', // 禁止空函数
'@typescript-eslint/no-use-before-define': 'off', // 在定义之前禁止使用变量
'@typescript-eslint/ban-ts-comment': 'off', // 禁止 @ts-<directive> 使用评论或在指令后要求描述
'@typescript-eslint/ban-types': 'off', // 禁止使用特定类型
'@typescript-eslint/no-non-null-assertion': 'off', // '!'不允许使用后缀运算符的非空断言
'@typescript-eslint/explicit-module-boundary-types': 'off', // 需要导出函数和类的公共类方法的显式返回和参数类型
'@typescript-eslint/no-unused-vars': [
'error',
{
argsIgnorePattern: '^_',
varsIgnorePattern: '^_'
}
], // 禁止未使用的变量
// vue
'vue/custom-event-name-casing': 'off', // 为自定义事件名称强制使用特定大小写
'vue/attributes-order': 'off', // 强制执行属性顺序
'vue/one-component-per-file': 'off', // 强制每个组件都应该在自己的文件中
'vue/html-closing-bracket-newline': 'off', // 在标签的右括号之前要求或禁止换行
'vue/multiline-html-element-content-newline': 'off', // 在多行元素的内容之前和之后需要换行符
'vue/singleline-html-element-content-newline': 'off', // 在单行元素的内容之前和之后需要换行符
'vue/attribute-hyphenation': 'off', // 对模板中的自定义组件强制执行属性命名样式
'vue/require-default-prop': 'off', // 需要 props 的默认值
'vue/html-indent': ['error', 2], // 在<template>中强制一致缩进
'vue/html-self-closing': 'off', // 执行自闭合的风格
'vue/max-attributes-per-line': 'off', // 强制每行属性的最大数量
'vue/multi-word-component-names': 'off', // 是否开启组件命名规则校验(强制多个单词以驼峰或'-'链接的命名规则)
// ESLint
'no-use-before-define': 'off', // 禁止在变量定义之前使用它们
'space-before-function-paren': 'off' // 强制在 function的左括号之前使用一致的空格
}
// overrides: [ // 若要开启组件命名规则校验,建议选这种方式
// {
// files: ['src/views/index.vue', 'src/views/**/index.vue'], // 匹配 views 和任意多级路径中的 index.vue
// rules: {
// 'vue/multi-word-component-names': 'off' // 给上面匹配的文件指定规则——关闭命名规则校验
// }
// }
// ]
})
对于 rules
规则集的配置,请参考以下官方规则:
三、配置 .eslintignore
eslint通过.eslintignore 文件或者在 package.json 文件中查找 eslintIgnore 键,来检查要忽略的文件。
比如你可以这样配置:
*.sh
*.md
*.woff
*.ttf
.vscode
.idea
.husky
.local
dist
node_modules
Dockerfile
/public
/docs
/bin
四、配置 prettier.config.js
- Print Width:打印宽度
- Tab Width:标签宽度
- Tabs:标签
- Semicolons:分号
- Quotes:引号
- Quote Props:引用对象中的属性
- JSX Quotes:在 JSX 中使用单引号而不是双引号
- Trailing Commas:尾部逗号
- Bracket Spacing:在对象文字中的括号之间打印空格。
- Bracket Line:括号线
- Arrow Function Parentheses:箭头函数括号
- Range:格式化的范围
- Parser:指定要使用的解析器。
- File Path:文件路径
- Require Pragma:需要编译指示
- Insert Pragma:插入编译指示
- Prose Wrap:散文包装
- HTML Whitespace Sensitivity:HTML 空白敏感性
- Vue files script and style tags indentation:Vue 文件脚本和样式标签缩进
- End of Line:行结束
- Embedded Language Formatting:嵌入式语言格式
prettier.config.js 配置案例:
module.exports = {
printWidth: 100, // 最大行长规则通常设置为 100 或 120。
tabWidth: 2, // 指定每个标签缩进级别的空格数。
useTabs: false, // 使用制表符而不是空格缩进行。
semi: false, // true(默认): 在每条语句的末尾添加一个分号。false:仅在可能导致 ASI 失败的行的开头添加分号。
vueIndentScriptAndStyle: true, // Vue 文件脚本和样式标签缩进
singleQuote: true, // 使用单引号而不是双引号
quoteProps: 'as-needed', // 引用对象中的属性时,仅在需要时在对象属性周围添加引号。
bracketSpacing: true, // 在对象文字中的括号之间打印空格。
trailingComma: 'none', // "none":没有尾随逗号。"es5": 在 ES5 中有效的尾随逗号(对象、数组等),TypeScript 中的类型参数中没有尾随逗号。"all"- 尽可能使用尾随逗号。
bracketSameLine: false, // 将>多行 HTML(HTML、JSX、Vue、Angular)元素放在最后一行的末尾,而不是单独放在下一行(不适用于自闭合元素)。
jsxSingleQuote: false, // 在 JSX 中使用单引号而不是双引号。
arrowParens: 'always', // 在唯一的箭头函数参数周围始终包含括号。
insertPragma: false, // 插入编译指示
requirePragma: false, // 需要编译指示
proseWrap: 'never', // 如果散文超过打印宽度,则换行
htmlWhitespaceSensitivity: 'strict', // 所有标签周围的空格(或缺少空格)被认为是重要的。
endOfLine: 'lf', // 确保在文本文件中仅使用 ( \n)换行,常见于 Linux 和 macOS 以及 git repos 内部。
rangeStart: 0, // 格式化文件时,回到包含所选语句的第一行的开头。
};
五、配置 .prettierignore
如果存在不想被 Prettier 格式化的文件,可以忽略格式化。
比如你可以这样配置:
/dist/*
/public/*
/node_modules/**
.local
.output.js
**/*.svg
**/*.sh
六、问题的处理
1、路径中不识别 @ 符
请去检查并完善 vite.config.ts
配置文件中是否对 @ 符进行了配置。没有的话,请参阅此文。
2、ts 不识别 jsx、tsx 类型的文件
报错:无法找到模块“xxx”的声明文件,xxx隐式拥有 “any“ 类型
请去检查并完善 tsconfig.json
配置文件。可参阅此文来解决此问题。
【参考文献】
在 Vue3 + Vite + TS 项目中配置 ESLint,让 VSCode 编辑器自动修复错误
Vue3+Vite+TS+Eslint(Airbnb规则)搭建生产项目,踩坑详记(一):项目初始化、引入ESLint
Vue3+Vite+TS+Eslint(Airbnb规则)搭建生产项目,踩坑详记(二):配置husky和lint-staged
vue3 + vite 项目搭建 - 配置eslint
Vue3 全家桶 + Element Plus + Vite + TypeScript + Eslint 项目配置最佳实践
【推荐阅读】
eslint-plugin-vue 官方文档
ESLint 中文官网文档:配置 ESLint
TypeScript ESLint 文档
配置 Prettier 的选项