纯JavaScript项目ESLint报'HTMLElement'等未定义错误的解决方法

问题场景 #

纯JavaScript项目里，ESLint对以下文件抛出no-undef错误：

• src/hello-world.component.js：HTMLElement、customElements未定义
• src/hello-world.component.spec.js：suite、test未定义

此前的TypeScript相关方案不适用，需通过修改ESLint配置放行这些全局变量。

解决方案 #

修改eslint.config.js，推荐通过环境变量配置（更简洁全面）解决问题，也可选择手动声明全局变量：

推荐配置（环境变量方式） #

import eslint from "@eslint/js";

export default [
    // 全局JS文件（含Web组件）配置
    {
        files: ["**/*.js", "**/*.cjs", "**/*.mjs"],
        languageOptions: {
            env: {
                browser: true, // 启用浏览器环境全局变量，解决HTMLElement、customElements报错
                es2022: true   // 适配代码中的ES2022语法特性
            }
        },
        rules: eslint.configs.recommended.rules
    },
    // 测试文件单独配置
    {
        files: ["**/*.spec.js"],
        languageOptions: {
            env: {
                browser: true, // 测试可能依赖浏览器环境
                mocha: true,   // 启用Mocha测试框架全局变量，解决suite、test报错
                es2022: true
            }
        },
        rules: eslint.configs.recommended.rules
    },
    {
        ignores: ["rollup.config.js", "web-test-runner.config.js"]
    }
]

备选配置（手动声明全局变量） #

如果不需要完整环境变量，可逐个声明需要的全局变量：

import eslint from "@eslint/js";

export default [
    // Web组件文件配置
    {
        files: ["**/*.js", "**/*.cjs", "**/*.mjs"],
        excludes: ["**/*.spec.js"],
        languageOptions: {
            globals: {
                HTMLElement: "readonly",
                customElements: "readonly"
            }
        },
        rules: eslint.configs.recommended.rules
    },
    // 测试文件配置
    {
        files: ["**/*.spec.js"],
        languageOptions: {
            globals: {
                suite: "readonly",
                test: "readonly"
            }
        },
        rules: eslint.configs.recommended.rules
    },
    {
        ignores: ["rollup.config.js", "web-test-runner.config.js"]
    }
]

说明 #

• browser: true：自动包含所有浏览器原生全局变量，无需逐个声明，适配Web组件开发场景。
• mocha: true：自动识别Mocha风格的测试全局变量，匹配@open-wc/testing的测试接口规范。
• readonly标记：表示这些全局变量为只读，ESLint不会对其赋值操作报错（若需修改可改为writable）。

内容的提问来源于stack exchange，提问作者Ole