Stylelint 默认只识别标准 CSS 语法,遇 SCSS 特有语法(如 $variable、@mixin)会报 unknown word;必须安装 stylelint-scss、配置 plugins 和 customSyntax: "postcss-scss",并确保 .stylelintrc.js 在项目根目录。

Stylelint 能直接约束 SCSS 和 CSS 的写法,但必须配对插件、配置和工作流,缺一不可。只装包不配 stylelint-scss,.scss 文件会报 unknown word;只写规则不进 Git Hook,规则就只是摆设。
为什么 .scss 文件一跑就报 unknown word?
这是最常踩的坑:Stylelint 默认只认标准 CSS 语法,遇到 @mixin、$variable、@extend 这类 SCSS 特有语法时直接懵掉。
- 必须安装
stylelint-scss插件:npm install --save-dev stylelint-scss - 配置中要同时声明
plugins和extends,不能只写一个:module.exports = { plugins: ['stylelint-scss'], extends: ['stylelint-config-standard', 'stylelint-config-scss'], rules: { 'scss/dollar-variable-pattern': '^var_', 'scss/at-rule-no-unknown': true } }; - 如果用
stylelint-config-standard-scss,它内部已包含stylelint-scss插件,但你仍需显式安装该包,否则extends会加载失败
怎么让规则在 VS Code 里实时生效?
VS Code 不会自动识别项目级 Stylelint 配置,必须手动指定校验语言和可执行路径。
- 装好
SublimeLinter-stylelint(Sublime)或Stylelint官方插件(VS Code)后,进设置搜stylelint.validate - 确保
stylelint.validate包含'css'、'scss'、'vue'(若项目含<style lang="scss"></style>) - 如果本地是项目内安装(
--save-dev),插件默认找不到stylelint命令——得在插件设置里填node_modules/.bin/stylelint的绝对路径
怎么防止有人绕过检查直接提交?
靠人自觉没用,得用 husky + lint-staged 在 git commit 前卡住。
- 先装依赖:
npm install husky lint-staged --save-dev - 在
package.json中加脚本和钩子:"scripts": { "lint:css": "stylelint \"src/**/*.{css,scss,vue}\" --fix" }, "lint-staged": { "*.{css,scss,vue}": "npm run lint:css" }, "husky": { "hooks": { "pre-commit": "lint-staged" } } - 注意:如果
stylelint.config.js放错位置(比如不在 Git 根目录),lint-staged运行时会静默跳过,不报错也不检查——务必确认文件名是.stylelintrc.js或stylelint.config.js,且导出的是 plain object
真正难的不是写几条规则,而是让所有人改掉“我写的没问题”的惯性。比如 selector-max-id: 0 看似简单,但一旦有人在 Vue 单文件组件里写了 #header,CI 就会挂。这种细节,只有嵌入编辑器提示 + 提交拦截 + CI 三道关卡,才压得住。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!











