Nuxt 2项目中Stylelint报多符号错误求助

问题场景 #

在VSCode中打开Nuxt 2项目时，鼠标悬停在样式元素上会显示大量错误提示（如未知符号、无效选择器），但项目控制台无报错，应用运行完全正常。

报错截图：

项目配置 #

package.json #

{
"dependencies": {
    "@nuxtjs/axios": "^5.13.6",
    "@nuxtjs/pwa": "^3.3.5",
    "core-js": "^3.25.3",
    "element-ui": "^2.15.10",
    "nuxt": "^2.17.0",
    "vue": "^2.7.10",
    "vue-server-renderer": "^2.7.10",
    "vue-template-compiler": "^2.7.10"
  },
  "devDependencies": {
    "@babel/eslint-parser": "^7.19.1",
    "@commitlint/cli": "^17.1.2",
    "@commitlint/config-conventional": "^17.1.0",
    "@nuxt/types": "^2.15.8",
    "@nuxt/typescript-build": "^2.1.0",
    "@nuxtjs/eslint-config-typescript": "^12.1.0",
    "@nuxtjs/eslint-module": "^3.1.0",
    "@nuxtjs/stylelint-module": "^4.1.0",
    "@nuxtjs/tailwindcss": "6.7.0",
    "@typescript-eslint/eslint-plugin": "^6.7.4",
    "@typescript-eslint/parser": "^6.7.4",
    "@vue/test-utils": "^1.3.0",
    "babel-core": "7.0.0-bridge.0",
    "babel-jest": "^29.1.2",
    "eslint": "^8.50.0",
    "eslint-config-prettier": "^8.5.0",
    "eslint-plugin-import": "^2.28.1",
    "eslint-plugin-jest": "^27.0.4",
    "eslint-plugin-json-format": "^2.0.1",
    "eslint-plugin-nuxt": "^4.0.0",
    "eslint-plugin-prettier": "^4.1.0",
    "eslint-plugin-simple-import-sort": "^10.0.0",
    "eslint-plugin-unused-imports": "^3.0.0",
    "eslint-plugin-vue": "^9.17.0",
    "husky": "^8.0.3",
    "jest": "^29.7.0",
    "jest-environment-jsdom": "^29.7.0",
    "jsonc-eslint-parser": "^2.3.0",
    "lint-staged": "^14.0.1",
    "postcss": "^8.4.31",
    "postcss-html": "^1.5.0",
    "postcss-scss": "^4.0.9",
    "prettier": "^2.7.1",
    "sass": "^1.69.0",
    "sass-loader": "^10.1.1",
    "stylelint": "^15.6.2",
    "stylelint-config-recommended-vue": "^1.4.0",
    "stylelint-config-standard": "^33.0.0",
    "stylelint-no-unsupported-browser-features": "^7.0.0",
    "stylelint-order": "^6.0.3",
    "ts-jest": "^29.0.3",
    "typescript": "^5.2.2",
    "vue-jest": "^3.0.4"
  }
}

.stylelint.js #

module.exports = {
  plugins: ['stylelint-no-unsupported-browser-features', 'stylelint-order'],
  customSyntax: 'postcss-scss',
  extends: ['stylelint-config-standard', 'stylelint-config-recommended-vue'],
  rules: {
    'color-hex-length': 'long',
    'declaration-block-no-redundant-longhand-properties': [
      true,
      {
        ignoreShorthands: ['flex-flow'],
      },
    ],
    'declaration-block-no-duplicate-properties': null,
    'at-rule-empty-line-before': [
      'always',
      {
        except: ['after-same-name'],
      },
    ],
    'property-no-unknown': [
      true,
      {
        ignoreProperties: ['composes', 'r'],
      },
    ],
    'unit-no-unknown': [
      true,
      {
        ignoreUnits: ['x'],
      },
    ],
    'order/order': [
      ['custom-properties', 'at-variables', 'declarations', 'at-rules', 'rules', 'less-mixins'],
      {
        severity: 'warning',
      },
    ],
    'order/properties-order': [
      [
        {
          emptyLineBefore: 'never',
          properties: ['content'],
        },
        {
          emptyLineBefore: 'never',
          properties: ['position', 'top', 'right', 'bottom', 'left', 'z-index'],
        },
        {
          emptyLineBefore: 'never',
          properties: [
            'box-sizing',
            'display',
            'flex',
            'flex-basis',
            'flex-direction',
            'flex-flow',
            'flex-grow',
            'flex-shrink',
            'flex-wrap',
            'align-content',
            'align-items',
            'align-self',
            'justify-content',
            'order',
            'margin',
            'margin-top',
            'margin-right',
            'margin-bottom',
            'margin-left',
            'padding',
            'padding-top',
            'padding-right',
            'padding-bottom',
            'padding-left',
            'min-width',
            'min-height',
            'max-width',
            'max-height',
            'width',
            'height',
            'float',
            'clear',
            'clip',
            'visibility',
            'overflow',
            'border',
            'border-top',
            'border-right',
            'border-bottom',
            'border-left',
            'border-width',
            'border-top-width',
            'border-right-width',
            'border-bottom-width',
            'border-left-width',
            'border-style',
            'border-top-style',
            'border-right-style',
            'border-bottom-style',
            'border-left-style',
            'border-radius',
            'border-top-left-radius',
            'border-top-right-radius',
            'border-bottom-right-radius',
            'border-bottom-left-radius',
            'border-color',
            'border-top-color',
            'border-right-color',
            'border-bottom-color',
            'border-left-color',
            'box-shadow',
          ],
        },
        {
          emptyLineBefore: 'never',
          properties: [
            'background',
            'background-attachment',
            'background-clip',
            'background-color',
            'background-image',
            'background-repeat',
            'background-position',
            'background-size',
          ],
        },
        {
          emptyLineBefore: 'never',
          properties: [
            'color',
            'font',
            'font-family',
            'font-size',
            'font-smoothing',
            'font-style',
            'font-variant',
            'font-weight',
            'letter-spacing',
            'line-height',
            'list-style',
            'text-align',
            'text-decoration',
            'text-indent',
            'text-overflow',
            'text-rendering',
            'text-shadow',
            'text-transform',
            'text-wrap',
            'vertical-align',
            'white-space',
            'word-spacing',
          ],
        },
      ],
      {
        severity: 'warning',
      },
    ],
    'block-no-empty': true,
    'rule-empty-line-before': ['always', { except: ['after-single-line-comment', 'first-nested'] }],
    'comment-no-empty': true,
    'comment-empty-line-before': 'never',
    'declaration-empty-line-before': [
      'always',
      {
        except: ['after-comment', 'after-declaration', 'first-nested'],
      },
    ],
    'no-duplicate-selectors': true,
    'no-duplicate-at-import-rules': true,
    'no-invalid-position-at-import-rule': null,
    'color-function-notation': 'legacy',
    'import-notation': 'string',
    'at-rule-no-unknown': null,
  },
  overrides: [
    {
      files: ['*.vue', '**/*.vue'],
      customSyntax: 'postcss-html',
    },
    {
      files: ['components/**/*.css', 'pages/**/*.css'],
      rules: {
        'alpha-value-notation': 'percentage',
      },
    },
  ],
}

解决方案 #

1. 修复Stylelint自定义语法冲突 #

全局设置customSyntax: 'postcss-scss'会导致Vue文件中的样式解析异常，需将语法配置按文件类型拆分到overrides中，同时添加Vue特有的伪类/伪元素忽略规则：
修改后的.stylelint.js核心部分：

module.exports = {
  plugins: ['stylelint-no-unsupported-browser-features', 'stylelint-order'],
  // 移除全局customSyntax配置
  extends: ['stylelint-config-standard', 'stylelint-config-recommended-vue'],
  rules: {
    // 保留原有规则不变
    // 新增：忽略Vue特有的伪类/伪元素
    'selector-pseudo-class-no-unknown': [true, {
      ignorePseudoClasses: ['deep', 'global']
    }],
    'selector-pseudo-element-no-unknown': [true, {
      ignorePseudoElements: ['v-deep', 'v-global', 'v-slotted']
    }]
  },
  overrides: [
    {
      files: ['*.scss', '**/*.scss'],
      customSyntax: 'postcss-scss' // 仅SCSS文件使用postcss-scss语法
    },
    {
      files: ['*.vue', '**/*.vue'],
      customSyntax: 'postcss-html' // Vue文件使用postcss-html解析
    },
    {
      files: ['components/**/*.css', 'pages/**/*.css'],
      rules: {
        'alpha-value-notation': 'percentage',
      },
    },
  ],
}

2. 配置VSCode Stylelint插件 #

打开VSCode设置（Ctrl+,/Cmd+,），添加或修改以下配置：

"stylelint.validate": [
  "css",
  "scss",
  "vue"
],
"stylelint.enable": true

3. 清除Stylelint缓存 #

执行命令清除缓存，避免旧缓存引发的误报：

npx stylelint --clear-cache

4. 重启VSCode #

完成上述配置后，重启VSCode让设置生效。

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