给 vite 创建的 Vue3 项目配置 ESLint

前言

本文是给用 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：
  • 代码格式化程序。
  • Prettier 2.5 发布：支持 TypeScript 4.5 新语法和 MDX v2 注释语法

推荐可选 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 规则集的配置，请参考以下官方规则：

• TypeScript ESLint Rules
• eslint-plugin-vue Available rules
• ESLint 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

配置 Prettier 的选项

• 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 的选项