Stylelint无法识别SCSS文件的典型表现是运行npx stylelint src/**/*.scss报Unknown word或Unexpected token，VS Code无提示，仅.css生效；根本原因是未安装stylelint-scss和postcss-scss插件，且配置中缺失overrides与customSyntax。
SCSS文件不被Stylelint识别的典型表现
运行 npx stylelint src/**/*.scss 报 Unknown word 或 Unexpected token，VS Code 里完全没提示，或者只对 .css 文件生效——这说明 Stylelint 根本没正确解析 SCSS 语法，不是规则松了，而是连基础解析都失败了。
必须安装的三个依赖缺一不可
Stylelint 默认只认标准 CSS，要支持 @mixin、$variable、嵌套等 SCSS 特性，得靠插件“假装理解”语法。以下三者必须同时存在：
-
stylelint（v16+ 推荐） -
stylelint-scss（提供 SCSS 专属规则和语法桥接） -
postcss-scss（作为customSyntax解析器，让 Stylelint 能读 .scss 文件）
漏装 postcss-scss 是最常被忽略的一环：它不报错，但所有 SCSS 特有语法都会被当垃圾字符处理。安装命令示例：
npm install --save-dev stylelint stylelint-scss postcss-scss
.stylelintrc.js 中 overrides 和 customSyntax 是关键
不能只靠 extends，必须显式告诉 Stylelint：“这些后缀的文件，用这个语法解析器”。否则 stylelint-config-standard-scss 里的规则根本不会触发。
立即学习“前端免费学习笔记（深入）”；
配置片段示例（注意大小写和路径通配）：
{
"extends": ["stylelint-config-standard-scss"],
"plugins": ["stylelint-scss"],
"overrides": [
{
"files": ["**/*.scss"],
"customSyntax": "postcss-scss"
}
],
"rules": {
"scss/dollar-variable-pattern": "^\$[a-z][a-zA-Z0-9]*$", // 强制 $ 变量小驼峰
"scss/at-rule-nested-empty-line-before": "always", // @include 前必须空行
"block-no-empty": true
}
}
常见坑：
-
customSyntax写成"postcss-sass"（少一个c）→ 解析失败 -
overrides.files写成["*.scss"]→ 不匹配子目录下的文件 - 用
stylelint-config-standard替代stylelint-config-standard-scss→ 大量 Sass 特有规则（如scss/selector-nest-combinator）直接失效
Vue/SFC 中的 <style lang="scss"> 需额外处理器
Stylelint 默认跳过单文件组件里的 <style> 块。想让它检查 <style lang="scss">，必须加 postcss-html 并在 overrides 中声明：
{
"overrides": [
{
"files": ["**/*.vue"],
"customSyntax": "postcss-html",
"rules": {
"at-rule-no-unknown": [true, { "ignoreAtRules": ["function", "if", "each", "include"] }]
}
},
{
"files": ["**/*.scss"],
"customSyntax": "postcss-scss"
}
]
}
注意：postcss-html 必须安装，且 at-rule-no-unknown 要忽略 SCSS 指令（否则 @include 会被当成非法 at-rule 报错）。
真正严格的 SCSS 规范，不在规则数量多，而在解析链完整：从文件识别 → 语法解析 → 规则加载 → Vue/SFC 支持，任一环节断掉，no-descending-specificity 或 max-nesting-depth 这类关键规则就只是摆设。
