如何解决ESLint（9/8版本）与Pug模板的兼容问题？

问题概述 #

技术栈包含Pug模板、JS（jQuery）、YAML、Stylus，尝试用eslint-plugin-pug让ESLint支持Pug模板，但遇到两个问题：

• 插件无法处理Pug文件中的script代码块
• 降级ESLint到v8后，运行npx eslint *.pug报错Parsing error: Unexpected token extends（因Pug模板使用继承语法）

现有配置 #

ESLint配置 #

import globals from 'globals';
import pluginJs from '@eslint/js';
import prettierPluginRecommended from 'eslint-plugin-prettier/recommended';
import pugPlugin from 'eslint-plugin-pug';

export default [
  pluginJs.configs.recommended,
  {
    files: ['**/*.js'],
    languageOptions: {
      sourceType: 'script',
      globals: {
        ...globals.browser,
        ...globals.jquery,
      },
    },
    rules: {
      'no-use-before-define': [
        'error',
        {
          functions: false,
          variables: true,
        },
      ],

      'no-unused-vars': 'warn',
      'no-undef': 'warn',
      'no-redeclare': 'warn',
      'no-console': 'warn',
      'no-duplicate-imports': 'error',
      'no-template-curly-in-string': 'error',
      'no-empty-function': 'error',
      'no-lonely-if': 'error',
      'no-magic-numbers': 'error',
      'no-var': 'error',

      'func-style': ['error', 'declaration'],
      'vars-on-top': 'error',
      'prefer-const': 'error',
      'require-await': 'error',

      'comma-dangle': ['error', 'always-multiline'],
      'default-case': 'error',
      'capitalized-comments': ['error', 'always'],
      'new-cap': ['error', { newIsCap: true }],
      'max-depth': ['error', 3],

      eqeqeq: 'error',
      camelcase: 'error',
      yoda: ['error', 'never', { exceptRange: true }],
    },
  },
  {
    files: ['**/*.pug'],
    plugins: { pugPlugin },
  },
  prettierPluginRecommended,
];

devDependencies #

"devDependencies": {
    "@eslint/js": "^9.11.0",
    "@prettier/plugin-pug": "^3.1.0",
    "eslint": "^8.57.1",
    "eslint-config-prettier": "^9.1.0",
    "eslint-plugin-prettier": "^5.2.1",
    "eslint-plugin-pug": "^1.2.5",
    "globals": "^15.9.0",
    "prettier": "^3.3.3",
    "prettier-plugin-stylus": "^0.1.0"
  }

解决方案 #

1. 修正ESLint配置 #

核心问题是未启用Pug处理器、插件键名错误，且未为提取的JS代码配置规则。修改后的配置如下：

import globals from 'globals';
import pluginJs from '@eslint/js';
import prettierPluginRecommended from 'eslint-plugin-prettier/recommended';
import pugPlugin from 'eslint-plugin-pug';

export default [
  pluginJs.configs.recommended,
  {
    files: ['**/*.js'],
    languageOptions: {
      sourceType: 'script',
      globals: {
        ...globals.browser,
        ...globals.jquery,
      },
    },
    rules: {
      'no-use-before-define': [
        'error',
        {
          functions: false,
          variables: true,
        },
      ],

      'no-unused-vars': 'warn',
      'no-undef': 'warn',
      'no-redeclare': 'warn',
      'no-console': 'warn',
      'no-duplicate-imports': 'error',
      'no-template-curly-in-string': 'error',
      'no-empty-function': 'error',
      'no-lonely-if': 'error',
      'no-magic-numbers': 'error',
      'no-var': 'error',

      'func-style': ['error', 'declaration'],
      'vars-on-top': 'error',
      'prefer-const': 'error',
      'require-await': 'error',

      'comma-dangle': ['error', 'always-multiline'],
      'default-case': 'error',
      'capitalized-comments': ['error', 'always'],
      'new-cap': ['error', { newIsCap: true }],
      'max-depth': ['error', 3],

      eqeqeq: 'error',
      camelcase: 'error',
      yoda: ['error', 'never', { exceptRange: true }],
    },
  },
  // Pug文件核心配置
  {
    files: ['**/*.pug'],
    plugins: { pug: pugPlugin }, // 修正插件键名为官方要求的"pug"
    processor: 'pug/pug', // 启用Pug处理器，自动提取并检查script块
  },
  // 为Pug中提取的JS代码配置规则和全局变量
  {
    files: ['**/*.pug/*.js'], // 匹配插件提取出的临时JS文件
    languageOptions: {
      sourceType: 'script',
      globals: {
        ...globals.browser,
        ...globals.jquery,
      },
    },
    rules: {
      // 复用已有JS规则或按需调整
      ...pluginJs.configs.recommended.rules,
      'no-unused-vars': 'warn',
      'no-undef': 'warn',
    },
  },
  prettierPluginRecommended,
];

2. 调整依赖版本 #

ESLint v8不兼容@eslint/jsv9.x，需删除该包：

"devDependencies": {
    "eslint": "^8.57.1",
    "@prettier/plugin-pug": "^3.1.0",
    "eslint-config-prettier": "^9.1.0",
    "eslint-plugin-prettier": "^5.2.1",
    "eslint-plugin-pug": "^1.2.5",
    "globals": "^15.9.0",
    "prettier": "^3.3.3",
    "prettier-plugin-stylus": "^0.1.0"
  }

3. 验证修复 #

执行完整的Pug文件检查命令：

npx eslint **/*.pug

原因说明 #

• 未指定processor: 'pug/pug'时，ESLint用JS解析器处理Pug文件，无法识别extends等Pug语法，导致解析错误
• 插件键名错误（pugPlugin应为pug），导致插件未正确加载
• 缺少提取后JS代码的配置，即使插件提取了script块，也无法应用ESLint规则检查

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