HTML内嵌脚本ESLint检查指南

你是否遇到过这种情况：在VS Code中编写HTML时，标签内的JavaScript代码可以正常编写，但ESLint却没有任何反应，既不显示波浪线也不报错？请不要急于认为自己的代码完美无缺，更可能的原因是ESLint根本没有检查这部分内容。

问题的关键在于，ESLint默认只识别.js、.jsx这类纯JavaScript文件。对于HTML文件，它将其视为一个整体文本，其中的块对它来说只是一段普通字符串，因此不会触发语法或规则检查。这就像将一份中文报告放入英文语法检查器，结果可想而知。

那么，如何让ESLint“理解”HTML中的脚本呢？答案是借助一个专门的“翻译官”——eslint-plugin-html插件。它的工作原理很直接：不是让ESLint去理解HTML，而是提取HTML文件内标签的内容，将其转换为虚拟的JavaScript片段，再交由ESLint原有的检查流程处理。

安装 eslint-plugin-html 并确认版本兼容性

首先，需要将插件安装到项目中。打开终端，在项目根目录下运行：

npm install --save-dev eslint-plugin-html

这里需要注意版本匹配问题。插件的不同版本对ESLint主版本有要求。例如，eslint-plugin-html@6.x需要ESLint v6.0.0或更高版本。如果你的项目使用的是当前较新的ESLint v8.57+ 或 v9.x，则建议安装与之兼容的eslint-plugin-html@7.x版本。

另外，如果你的项目同时使用了Vue单文件组件并配置了eslint-plugin-vue，则需要留意。eslint-plugin-vue会优先处理.vue文件中的块，此时eslint-plugin-html可能会被绕过。具体哪个插件生效，取决于ESLint配置中overrides部分的优先级设置。

安装完成后，一个稳妥的确认方法是运行：

npm list eslint eslint-plugin-html

这可以清晰地列出已安装的版本，确保没有发生对等依赖冲突。有时安装看似成功，但版本不匹配会导致插件静默失效。

在 VS Code 中启用 .html 文件的 ESLint 验证

安装插件只是第一步。接下来，必须告知你的代码编辑器——这里特指VS Code——让它对.html文件也启用ESLint检查。缺少这一步配置，编辑器中依然不会有任何提示。

操作路径如下：

1. 打开VS Code的设置。快捷键是Ctrl+,（Windows/Linux）或Cmd+,（Mac）。
2. 在搜索框输入“eslint.validate”。
3. 找到“ESLint: Validate”配置项，点击“在settings.json中编辑”。

关键点在于，你需要在settings.json文件中，确保eslint.validate数组里包含"html"。注意，是"html"，而非"htm"或其他变体。

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

不过，这里还有一个版本变化需要注意。如果你使用的是ESLint v8.40或更高版本，那么eslint.validate这个设置项已被标记为废弃。新的配置方式是在eslint.options中指定extensions：

{
  "eslint.options": {
    "extensions": [".js", ".jsx", ".html"]
  }
}

配置修改后，务必重启VS Code或重载窗口。可以按Ctrl+Shift+P（或Cmd+Shift+P）打开命令面板，输入“Reload Window”并执行。否则，新设置可能不会立即生效。

在 .eslintrc.js 中正确注册插件和解析逻辑

编辑器配置完成后，接下来需要在ESLint自身的配置文件中正式启用插件的处理能力。

打开项目根目录下的.eslintrc.js文件（也可能是.eslintrc.json或.eslintrc）。首先，在plugins数组中添加"html"：

plugins: ["html"]

但这只是声明了依赖。真正让插件工作的是“处理器”。你需要在配置的根对象中显式指定处理器：

processor: "html/html"

如果你希望配置更精准，例如只检查src目录下的HTML文件，可以使用overrides配置项：

overrides: [
  {
    files: ["src/**/*.html"], // 匹配src目录下所有html文件
    processor: "html/html"
  }
]

使用overrides时需要注意，其内部的配置会继承顶层的env、globals等设置。例如，HTML内联脚本中通常会使用document、window等浏览器全局对象，那么请确保顶层配置中已开启env: { browser: true }。不要在overrides中重复编写这些全局配置，除非你需要覆盖它们。

最后提醒一点，eslint-plugin-html插件本身不提供任何额外的ESLint规则，它只提供处理器功能。因此，不要将其添加到extends数组中，那是放置规则集的地方。

常见失效场景和快速排查路径

按照上述步骤配置后，理论上应该生效。但如果编辑器中依然没有提示，不必慌张，很可能遇到了以下几个常见问题：

• 依赖未安装：检查package.json的devDependencies中是否有eslint-plugin-html。确保是使用--save-dev在本地安装的，而非全局安装。
• VS Code工作区不正确：VS Code打开的并非包含.eslintrc.js配置文件的项目根目录，导致其找不到ESLint配置。
• 脚本标签带有src属性：eslint-plugin-html只处理内联在HTML文件中的脚本（即）。对于通过src引入的外部JS文件（如），它不会加载和检查。外部文件需要ESLint直接检查其本身。
• 非标准type属性：插件默认只识别text/javascript、module、空的type以及application/javascript。如果你的标签使用了type="application/json"或type="text/template"等，它会被忽略。
• 配置文件未被识别：查看VS Code底部状态栏的ESLint输出面板（点击ESLint图标）。如果显示“No ESLint configuration found”，说明它未找到配置文件。请确认你的配置文件名称是.eslintrc.js（或.eslintrc.json等标准名称），并且放置在项目根目录。

总而言之，最容易被忽略的就是“处理器声明”和“VS Code验证配置”这两步必须同时完成，缺一不可。这个插件就像一个翻译器，它的任务是将HTML中的JavaScript片段“喂”给ESLint的核心检查引擎。至于HTML标签本身的结构问题，例如标签是否闭合、属性格式是否正确，则不在其职责范围内。要检查这些，你需要寻求像eslint-plugin-html-req这类专门处理HTML的linter，或其他HTML语法检查工具。