用户指南

💿 安装

通过 npm

bash

npm install --save-dev eslint eslint-plugin-vue

通过 yarn

bash

yarn add -D eslint eslint-plugin-vue

要求

ESLint v6.2.0 及以上版本
Node.js v14.17.x、v16.x 及以上版本

📖 使用方法

配置 (`eslint.config.js`)

使用 eslint.config.js 文件配置规则。这是 ESLint v9 中的默认设置，但从 ESLint v8.57.0 开始就可以使用。另请参阅：https://eslint.org.cn/docs/latest/use/configure/configuration-files-new。

示例 eslint.config.js

import pluginVue from 'eslint-plugin-vue'
export default [
  // add more generic rulesets here, such as:
  // js.configs.recommended,
  ...pluginVue.configs['flat/recommended'],
  // ...pluginVue.configs['flat/vue2-recommended'], // Use this if you are using Vue.js 2.x.
  {
    rules: {
      // override/add rules settings here, such as:
      // 'vue/no-unused-vars': 'error'
    }
  }
]

请参阅规则列表以获取此插件提供的 configs 和 rules。

捆绑配置 (`eslint.config.js`)

此插件提供了一些预定义的配置。您可以通过将以下配置添加到 eslint.config.js 来使用它们。（此插件中的所有平面配置都以数组形式提供，因此在将它们与其他配置组合时需要使用扩展语法。）

*.configs["flat/base"] ... 启用正确 ESLint 解析的设置和规则。
使用 Vue.js 3.x 的配置
- *.configs["flat/essential"] ... base，以及防止错误或意外行为的规则。
- *.configs["flat/strongly-recommended"] ... 以上，以及可以显著提高代码可读性和/或开发体验的规则。
- *.configs["flat/recommended"] ... 以上，以及强制执行主观社区默认值以确保一致性的规则。
使用 Vue.js 2.x 的配置
- *.configs["flat/vue2-essential"] ... base，以及防止错误或意外行为的规则。
- *.configs["flat/vue2-strongly-recommended"] ... 以上，以及可以显著提高代码可读性和/或开发体验的规则。
- *.configs["flat/vue2-recommended"] ... 以上，以及强制执行主观社区默认值以确保一致性的规则

报告规则

默认情况下，来自 **base** 和 **essential** 类别的所有规则都会报告 ESLint 错误。其他规则 - 因为它们不涵盖应用程序中的潜在错误 - 会报告警告。这意味着什么？默认情况下 - 什么都没有，但如果您愿意 - 您可以设置一个阈值，并在达到一定数量的警告后中断构建，而不是任何警告。更多信息请参阅此处。

配置 (`.eslintrc`)

在 ESLint < v9 中使用 .eslintrc.* 文件配置规则。另请参阅：https://eslint.org.cn/docs/latest/use/configure/。

示例 .eslintrc.js

module.exports = {
  extends: [
    // add more generic rulesets here, such as:
    // 'eslint:recommended',
    'plugin:vue/vue3-recommended',
    // 'plugin:vue/recommended' // Use this if you are using Vue.js 2.x.
  ],
  rules: {
    // override/add rules settings here, such as:
    // 'vue/no-unused-vars': 'error'
  }
}

请参阅规则列表以获取此插件提供的 extends 和 rules。

捆绑配置 (`.eslintrc`)

此插件提供了一些预定义的配置。您可以通过将以下配置添加到 extends 来使用它们。

"plugin:vue/base" ... 启用正确 ESLint 解析的设置和规则。
使用 Vue.js 3.x 的配置
- "plugin:vue/vue3-essential" ... base，以及防止错误或意外行为的规则。
- "plugin:vue/vue3-strongly-recommended" ... 以上，以及可以显著提高代码可读性和/或开发体验的规则。
- "plugin:vue/vue3-recommended" ... 以上，以及强制执行主观社区默认值以确保一致性的规则。
使用 Vue.js 2.x 的配置
- "plugin:vue/essential" ... base，以及防止错误或意外行为的规则。
- "plugin:vue/strongly-recommended" ... 以上，以及可以显著提高代码可读性和/或开发体验的规则。
- "plugin:vue/recommended" ... 以上，以及强制执行主观社区默认值以确保一致性的规则

报告规则

Vue.js 3.x 支持状态

此插件支持 Vue.js 3.2 的基本语法、<script setup> 和 CSS 变量注入，但不支持 Vue.js 3.2 的实验性功能 ref sugar。
如果您在使用这些功能时遇到问题，请参阅常见问题解答。如果找不到解决方案，请搜索问题，如果问题不存在，请打开一个新问题。

从命令行运行 ESLint

如果要从命令行运行 eslint，请确保使用 --ext 选项或 glob 模式包含 .vue 扩展名，因为 ESLint 默认情况下仅以 .js 文件为目标。

示例

bash

eslint --ext .js,.vue src
eslint "src/**/*.{js,vue}"

提示

如果您安装了 @vue/cli-plugin-eslint，则应该将 lint 脚本添加到 package.json 中。这意味着您可以直接运行 yarn lint 或 npm run lint。

如何使用自定义解析器？

如果要使用自定义解析器，例如 @babel/eslint-parser 或 @typescript-eslint/parser，则必须使用 parserOptions.parser 选项而不是 parser 选项。因为此插件需要 vue-eslint-parser 来解析 .vue 文件，所以如果您覆盖 parser 选项，此插件将无法工作。

diff

- "parser": "@typescript-eslint/parser",
+ "parser": "vue-eslint-parser",
  "parserOptions": {
+     "parser": "@typescript-eslint/parser",
      "sourceType": "module"
  }

完整示例

.eslintrceslint.config.js

json

{
  "root": true,
  "plugins": ["@typescript-eslint"],
  "extends": [
    "eslint:recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:vue/vue3-recommended"
  ],
  "parser": "vue-eslint-parser",
  "parserOptions": {
    "parser": "@typescript-eslint/parser"
  }
}

import js from '@eslint/js'
import eslintPluginVue from 'eslint-plugin-vue'
import ts from 'typescript-eslint'

export default ts.config(
  js.configs.recommended,
  ...ts.configs.recommended,
  ...eslintPluginVue.configs['flat/recommended'],
  {
    files: ['*.vue', '**/*.vue'],
    languageOptions: {
      parserOptions: {
        parser: '@typescript-eslint/parser'
      }
    }
  }
)

parserOptions.parser 选项还可以指定一个对象来指定多个解析器。有关更多详细信息，请参阅 vue-eslint-parser 自述文件。

ESLint 如何检测组件？

所有与组件相关的规则都适用于通过以下任何检查的代码

Vue.component() 表达式
Vue.extend() 表达式
Vue.mixin() 表达式
app.component() 表达式
app.mixin() 表达式
createApp() 表达式
defineComponent() 表达式
.vue 或 .jsx 文件中的 export default {}

但是，如果您想在任何自定义 Vue 组件对象中利用这些规则，则可能需要使用特殊注释 // @vue/component，该注释将下一行中的对象标记为任何文件中的 Vue 组件，例如

// @vue/component
const CustomComponent = {
  name: 'custom-component',
  template: '<div></div>'
}

Vue.component('AsyncComponent', (resolve, reject) => {
  setTimeout(() => {
    // @vue/component
    resolve({
      name: 'async-component',
      template: '<div></div>'
    })
  }, 500)
})

通过 `` 禁用规则

您可以在 <template> 和 .vue 文件的块级使用  之类的 HTML 注释来临时禁用某个规则。

例如

vue

<template>
  <!-- eslint-disable-next-line vue/max-attributes-per-line -->
  <div a="1" b="2" c="3" d="4">
  </div>
</template>

如果您想在 <template> 中禁用 eslint-disable 功能，请禁用 vue/comment-directive 规则。

解析器选项

此插件使用 vue-eslint-parser。对于 parserOptions，您可以使用 vue-eslint-parser 的 vueFeatures 选项。

json

{
  "parser": "vue-eslint-parser",
  "parserOptions": {
    "vueFeatures": {
      "filter": true,
      "interpolationAsNonHTML": false,
    }
  }
}

有关更多详细信息，请参阅 vue-eslint-parser 的 parserOptions.vueFeatures 文档。

💻 编辑器集成

Visual Studio Code

使用 Microsoft 官方提供的 dbaeumer.vscode-eslint 扩展。

您必须配置扩展的 eslint.validate 选项以检查 .vue 文件，因为默认情况下该扩展仅针对 *.js 或 *.jsx 文件。

示例 .vscode/settings.json

json

{
  "eslint.validate": [
    "javascript",
    "javascriptreact",
    "vue"
  ]
}

如果您使用 Vetur 插件，请设置 "vetur.validation.template": false 以避免默认的 Vetur 模板验证。有关更多信息，请查看 Vetur 文档。

Sublime Text

使用 Package Control 安装 SublimeLinter 及其 ESLint 扩展 SublimeLinter-eslint。

在菜单中，转到 首选项 > 软件包设置 > SublimeLinter > 设置 并粘贴以下内容

json

{
  "linters": {
    "eslint": {
      "selector": "text.html.vue, source.js - meta.attribute-with-value"
    }
  }
}

Atom 编辑器

进入 设置 -> 软件包 -> linter-eslint，在“要运行 eslint 的范围列表”选项下，添加 text.html.vue。您可能需要重新启动 Atom。

IntelliJ IDEA / JetBrains WebStorm

在“设置/偏好设置”对话框（Cmd+,/Ctrl+Alt+S）中，在“语言和框架”下选择 JavaScript，然后在“代码质量工具”下选择 ESLint。在打开的 ESLint 页面上，选中“启用”复选框。

如果您的 ESLint 配置已更新（手动或从您的版本控制更新），请在编辑器中打开它，然后在上下文菜单中选择“应用 ESLint 代码样式规则”。

阅读更多：JetBrains - ESLint

❓ 常见问题解答

“使用最新的 vue-eslint-parser”错误是什么？

大多数 eslint-plugin-vue 规则都需要 vue-eslint-parser 来检查 <template> AST。

确保您的 .eslintrc 中有以下设置之一

"extends": ["plugin:vue/vue3-recommended"]
"extends": ["plugin:vue/base"]

如果您已经在使用其他解析器（例如 "parser": "@typescript-eslint/parser"），请将其移至 parserOptions 中，这样它就不会与该插件配置使用的 vue-eslint-parser 冲突

diff

- "parser": "@typescript-eslint/parser",
+ "parser": "vue-eslint-parser",
  "parserOptions": {
+     "parser": "@typescript-eslint/parser",
      "ecmaVersion": 2020,
      "sourceType": "module"
  }

另请参阅：“如何使用自定义解析器？”部分。

为什么它在 .vue 文件上不起作用？

确保您的配置中没有 eslint-plugin-html。 eslint-plugin-html 从 <script> 标签中提取内容，但 eslint-plugin-vue 需要 <script> 标签和 <template> 标签才能区分单文件组件中的模板和脚本。

diff

  "plugins": [
    "vue",
-   "html"
  ]

确保您的工具已设置为 lint .vue 文件。
- CLI 默认情况下仅针对 .js 文件。您必须使用 --ext 选项或 glob 模式指定其他扩展名。例如 eslint "src/**/*.{js,vue}" 或 eslint src --ext .vue。如果您使用 @vue/cli-plugin-eslint 和 vue-cli-service lint 命令，则无需担心这一点。
- 如果您在配置编辑器时遇到问题，请阅读编辑器集成

与 Prettier 冲突

使用 eslint-config-prettier 以使 Prettier 不与该插件提供的可共享配置冲突。

示例 .eslintrc.js

module.exports = {
  // ...
  extends: [
    // ...
    // 'eslint:recommended',
    // ...
    'plugin:vue/vue3-recommended',
    // ...
    'prettier'
    // Make sure "prettier" is the last element in this list.
  ],
  // ...
}

如果 Prettier 与您设置的规则冲突，请关闭该规则。例如，如果您在 rules 中将 vue/html-indent 配置为 error，但它与 Prettier 冲突，请删除该行

diff

module.exports = {
  // ...
  rules: {
    // ...
-    "vue/html-indent": "error",
    // ...
  },
  // ...
}

使用 JSX

如果您正在使用 JSX，则需要在 ESLint 配置中启用 JSX。

diff

  "parserOptions": {
      "ecmaVersion": 2020,
      "ecmaFeatures": {
+         "jsx": true
      }
  }

另请参阅 ESLint - 指定解析器选项。

在 .vue 文件中将 JSX 与 TypeScript (TSX) 一起使用时，也需要相同的配置。
另请参阅此处。
请注意，在使用 jsx: true 时，不能使用尖括号类型断言样式（var x = <foo>bar;）。

Visual Studio Code 问题

在 ESLint 配置文件中关闭该规则不会忽略警告。
使用  注释不会抑制警告。
显示重复的警告。
使用了 @babel/eslint-parser，但模板仍然显示 vue/no-parsing-error 警告。

您需要通过将 vetur.validation.template: false 添加到 .vscode/settings.json 来关闭 Vetur 的模板验证。

另请参阅：“Visual Studio Code”部分和 Vetur - Linting。

与 `<script setup>` 配合使用效果不佳

`<template>` 中使用的变量会被 `no-unused-vars` 规则警告

您需要使用 vue-eslint-parser v9.0.0 或更高版本。

以前您必须使用 vue/script-setup-uses-vars 规则，现在不再需要了。

编译器宏（例如 `defineProps` 和 `defineEmits`）会生成 `no-undef` 警告

您需要使用 vue-eslint-parser v9.0.0 或更高版本。

以前您必须使用 vue/setup-compiler-macros 环境，现在不再需要了。

使用顶级 `await` 时出现解析错误

使用 ESLint <= v7.x

ESLint v7.x 附带的解析器 espree 不理解 ES2022 的语法，因此它也不能解析顶级 await。
但是，espree >= v8 可以理解 ES2022 的语法并解析顶级 await。
您安装 espree >= v8 并在您的配置中指定 "espree" 和 ES2022，解析器将能够解析它。

module.exports = {
  parser: 'vue-eslint-parser',
  parserOptions: {
    parser: 'espree', // <-
    ecmaVersion: 2022, // <-
    sourceType: 'module'
  },
}

但是，请注意，espree v8+ 生成的 AST 可能无法与 ESLint v7.x 的某些规则很好地配合使用。

使用 ESLint >= v8.x

您需要为 parserOptions.ecmaVersion 指定 2022 或 "latest"。

module.exports = {
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module'
  },
}

其他问题

尝试搜索现有问题。如果它不存在，您应该打开一个新问题并共享您的存储库以重现该问题。

自动导入支持

在 Nuxt 3 或使用 unplugin-auto-import 时，Vue API 可以自动导入。为了使 vue/no-ref-as-operand 或 vue/no-watch-after-await 等规则与它们一起正常工作，您可以在 ESLint 的 globals 选项中指定它们。

.eslintrceslint.config.js

json

{
  "globals": {
    "ref": "readonly",
    "computed": "readonly",
    "watch": "readonly",
    "watchEffect": "readonly",
    // ...more APIs
  }
}

export default [
  {
    languageOptions: {
      globals: {
        ref: 'readonly',
        computed: 'readonly',
        watch: 'readonly',
        watchEffect: 'readonly',
        // ...more APIs
      }
    }
  }
]

用户指南 ​

💿 安装 ​

📖 使用方法 ​

配置 (eslint.config.js) ​

捆绑配置 (eslint.config.js) ​

配置 (.eslintrc) ​

捆绑配置 (.eslintrc) ​

从命令行运行 ESLint ​

如何使用自定义解析器？ ​

ESLint 如何检测组件？ ​

通过  禁用规则 ​

解析器选项 ​

💻 编辑器集成 ​

Visual Studio Code ​

Sublime Text ​

Atom 编辑器 ​

IntelliJ IDEA / JetBrains WebStorm ​

❓ 常见问题解答 ​

“使用最新的 vue-eslint-parser”错误是什么？ ​

为什么它在 .vue 文件上不起作用？ ​

与 Prettier 冲突 ​

使用 JSX ​

Visual Studio Code 问题 ​

与 <script setup> 配合使用效果不佳 ​

<template> 中使用的变量会被 no-unused-vars 规则警告 ​

编译器宏（例如 defineProps 和 defineEmits）会生成 no-undef 警告 ​

使用顶级 await 时出现解析错误 ​

使用 ESLint <= v7.x ​

使用 ESLint >= v8.x ​

其他问题 ​

自动导入支持 ​

用户指南

💿 安装

📖 使用方法

配置 (`eslint.config.js`)

捆绑配置 (`eslint.config.js`)

配置 (`.eslintrc`)

捆绑配置 (`.eslintrc`)

从命令行运行 ESLint

如何使用自定义解析器？

ESLint 如何检测组件？

通过 `` 禁用规则

解析器选项

💻 编辑器集成

Visual Studio Code

Sublime Text

Atom 编辑器

IntelliJ IDEA / JetBrains WebStorm

❓ 常见问题解答

“使用最新的 vue-eslint-parser”错误是什么？

为什么它在 .vue 文件上不起作用？

与 Prettier 冲突

使用 JSX

Visual Studio Code 问题

与 `<script setup>` 配合使用效果不佳

`<template>` 中使用的变量会被 `no-unused-vars` 规则警告

编译器宏（例如 `defineProps` 和 `defineEmits`）会生成 `no-undef` 警告

使用顶级 `await` 时出现解析错误

使用 ESLint <= v7.x

使用 ESLint >= v8.x

其他问题

自动导入支持