拆分Vue单文件组件后ESLint误报未使用变量的解决办法

我们将Vue单文件组件拆分为component.vue、styles.scss和template.html，示例代码如下：

<script setup lang="ts">
// Common elements
import Category from '@/components/Elements/Category/Category.vue';

// COMPOSABLES
const localePath = useLocalePath();

// DATA
const session = ref(getSession());
</script>

<template src="./CustomTable.html" />
<style lang="scss" src="./custom-table.scss" />

尽管Category、localePath和session均在./CustomTable.html中使用，但ESLint仍给出如下未使用变量的警告：

3:8  warning  'Category' is defined but never used             @typescript-eslint/no-unused-vars
6:7  warning  'localePath' is assigned a value but never used  @typescript-eslint/no-unused-vars
9:7  warning  'session' is assigned a value but never used     @typescript-eslint/no-unused-vars

我们知道可以使用eslint-disable指令屏蔽警告，但这会忽略真正未使用的变量；也可通过defineExpose({ Category, localePath, session })暴露变量，但我们不希望在非必要时进行暴露。请问是否有办法让ESLint检测关联模板文件中的变量使用？或者有什么其他合理的解决方案？

以下是我们的eslintrc.ts配置：

{
  "env": {
    "browser": true,
    "es2021": true,
    "node": true,
    "vue/setup-compiler-macros": true
  },
  "extends": [
    "eslint:recommended",
    "plugin:vue/vue3-recommended",
    "@nuxtjs/eslint-config-typescript",
    "plugin:@typescript-eslint/recommended",
    "prettier",
    "plugin:storybook/recommended"
  ],
  "overrides": [],
  "parser": "vue-eslint-parser",
  "parserOptions": {
    "parser": "@typescript-eslint/parser"
  },
  "plugins": ["vue", "@typescript-eslint"],
  "rules": {
    "no-debugger": "off",
    "vue/multi-word-component-names": "off",
    "@typescript-eslint/no-explicit-any": "off",
    "vue/no-reserved-component-names": "off",
    "import/no-named-as-default": "off",
    "arrow-body-style": ["error", "as-needed"],
    "padding-line-between-statements": ["error", { "blankLine": "always", "prev": "*", "next": "if" }]
  }
}

解决方案 #

1. 让vue-eslint-parser识别外部HTML模板 #

vue-eslint-parser默认不会解析通过src引用的外部模板文件，需要在配置里指定它要扫描的模板扩展名，让.html文件被当作Vue模板处理。

修改eslintrc.ts中的parserOptions，添加vue配置：

"parserOptions": {
  "parser": "@typescript-eslint/parser",
  "vue": {
    "templateParserOptions": {
      "fileExtensions": [".vue", ".html"] // 加入.html扩展名，让解析器识别它
    }
  }
}

同时在overrides里添加对.html文件的规则继承，确保ESLint用Vue规则校验这些文件：

"overrides": [
  {
    "files": ["*.html"],
    "extends": ["plugin:vue/vue3-recommended"],
    "rules": {
      "vue/no-multiple-template-root": "off" // Vue3支持多根模板，无需这个规则的话可以关闭
    }
  }
]

2. 用Vue官方的未使用变量规则替代TS规则 #

@typescript-eslint/no-unused-vars无法感知Vue模板中的变量使用，而Vue官方插件的vue/no-unused-vars规则专门针对Vue场景优化，能识别<script setup>中在模板（包括外部模板）里用到的变量。

在rules中修改：

"rules": {
  // ... 保留其他原有规则
  "@typescript-eslint/no-unused-vars": "off", // 禁用TS的未使用变量规则
  "vue/no-unused-vars": ["error", {
    "vars": "all",
    "args": "none",
    "varsIgnorePattern": "^_" // 可选：忽略下划线开头的临时变量
  }]
}

3. 确保ESLint扫描包含HTML文件 #

检查你的lint脚本，确保运行ESLint时包含.html扩展名，比如在package.json中：

"scripts": {
  "lint": "eslint . --ext .vue,.ts,.js,.html"
}

4. 临时权宜方案：添加注释标记 #

如果上面的配置暂时无法生效，可以给变量添加注释明确标记它在模板中使用，避免ESLint误报：

import Category from '@/components/Elements/Category/Category.vue'; /* used in template */
const localePath = useLocalePath(); /* used in template */
const session = ref(getSession()); /* used in template */

内容的提问来源于stack exchange，提问作者Toni Michel Caubet