Vue3 SFC引入外部模板时ESLint报no-unused-vars错误如何解决

问题复现 #

使用<script setup>（组合式API+TS）编写Vue单文件组件时，按照官方SFC规范将模板内容拆分到独立HTML文件，通过<template>标签的src属性引入，代码运行完全正常，但ESLint持续抛出变量未使用的误报：

ESLint: 'person' is assigned a value but never used.(@typescript-eslint/no-unused-vars)

触发报错的代码结构 #

Person.vue

<script setup lang="ts">
import { ref } from "vue";
const person = ref(0);
</script>
<template src="./Person.html"></template>

Person.html

{{ person }}

将模板内容直接内嵌到.vue文件的<template>标签中时，报错完全消失：
Person.vue

<script setup lang="ts">
import { ref } from "vue";
const person = ref(0);
</script>
<template>
  {{ person }}
</template>

当前使用的ESLint配置（.eslintrc.cjs） #

require("@rushstack/eslint-patch/modern-module-resolution");

module.exports = {
  root: true,
  extends: [
    "plugin:vue/vue3-recommended",
    "eslint:recommended",
    "@vue/eslint-config-typescript/recommended",
    "@vue/eslint-config-prettier",
  ],
  parser: "vue-eslint-parser",
  overrides: [
    {
      files: ["cypress/integration/**.spec.{js,ts,jsx,tsx}"],
      extends: ["plugin:cypress/recommended"],
    },
  ],
};

根因 #

报错的核心原因是默认配置下vue-eslint-parser不会主动读取src属性引入的外部模板文件内容，无法感知<script setup>中定义的变量已在外部模板中被引用，因此触发@typescript-eslint/no-unused-vars规则的误判。

可行解决方案 #

方案1：开启外部模板解析配置（推荐） #

先将项目内的eslint-plugin-vue、vue-eslint-parser依赖升级到v9.0.0及以上版本，之后在ESLint配置中添加parserOptions.vueFeatures.externalTemplates配置项，开启外部模板内容解析能力：

require("@rushstack/eslint-patch/modern-module-resolution");

module.exports = {
  root: true,
  extends: [
    "plugin:vue/vue3-recommended",
    "eslint:recommended",
    "@vue/eslint-config-typescript/recommended",
    "@vue/eslint-config-prettier",
  ],
  parser: "vue-eslint-parser",
  // 新增以下配置
  parserOptions: {
    vueFeatures: {
      externalTemplates: true
    }
  },
  overrides: [
    {
      files: ["cypress/integration/**.spec.{js,ts,jsx,tsx}"],
      extends: ["plugin:cypress/recommended"],
    },
  ],
};

配置完成后重启IDE的ESLint服务，即可正常识别外部模板中的变量引用，消除误报。

方案2：替换未使用变量校验规则 #

如果暂时无法升级依赖，可以关闭TS自带的未使用变量校验，改用Vue官方ESLint插件提供的vue/no-unused-vars规则做校验，该规则对Vue SFC的模板场景适配更好：
在配置中添加rules节点：

module.exports = {
  // 其他原有配置保持不变
  rules: {
    "@typescript-eslint/no-unused-vars": "off",
    "vue/no-unused-vars": "error"
  }
}

注意：该方案同样需要eslint-plugin-vue版本不低于v8.0.0，否则仍可能出现外部模板识别失败的问题。

方案3：单行注释忽略报错（临时方案） #

如果只有少量文件使用外部模板，也可以直接在变量定义前加ESLint注释，跳过该行的未使用变量校验：

<script setup lang="ts">
import { ref } from "vue";
// eslint-disable-next-line @typescript-eslint/no-unused-vars
const person = ref(0);
</script>
<template src="./Person.html"></template>

该方案不需要修改全局配置，但每个模板用到的变量都需要手动加注释，维护成本较高，仅适合临时应急使用。

内容的提问来源于stack exchange，提问作者Marc von Brockdorff