配置文件不生效需确认加载路径和导出方式：必须位于当前工作目录，文件名为stylelint.config.js等合法名称，且用module.exports导出对象；SCSS/Vue等需配置customSyntax和validate语言模式；CI环境需统一路径、Node版本及依赖。
配置文件不生效？先看加载路径和导出方式
Stylelint 不会自动向上查找配置，它只认当前工作目录下的 stylelint.config.js、.stylelintrc.js 或 stylelint.config.cjs。常见现象是运行 npx stylelint *.css 完全没反应——其实压根没加载规则。
必须满足三个条件：
- 文件名严格匹配（别用
.stylelintrc无后缀，容易误读） - 放在执行命令时的当前工作目录（CI 脚本里
cd到子目录再跑就失效） - 用
module.exports = { ... }导出对象，不是函数或export default
示例正确写法：
module.exports = {
extends: ['stylelint-config-standard'],
rules: {
'color-hex-case': 'lower',
'no-empty-source': null
}
};
SCSS/Less/Vue SFC 文件报 unknown word 错误？缺 customSyntax
默认 stylelint 只处理纯 CSS，遇到 .scss 里的 @mixin 或 Vue 单文件组件里的 <style lang="scss"> 就会报错。
解决方法分两步：
立即学习“前端免费学习笔记（深入）”；
- 装对应解析器：比如
npm install --save-dev postcss-scss - 在配置中显式声明：
"customSyntax": "postcss-scss"
注意：如果用了 stylelint-scss 插件，还必须在 plugins 数组里加进去，否则插件规则不生效。
Vue Composition Analyzer
下载
分析 Vue 3 Composition API 使用情况——审计响应式模式、可组合函数设计、ref 与 reactive 的选择、计算属性、watcher 使用及组件……
VS Code 里没提示？检查语言绑定和 validate 配置
stylelint.vscode-stylelint 插件默认只校验 css、postcss、html 语言模式，对 vue、svelte 等文件中的 <style> 块完全静默。
手动启用方式：
- 打开 VS Code 设置，搜
stylelint.validate - 把
vue、scss等加进数组：["css", "scss", "vue"] - 确保文件语言模式正确（右下角显示 “Vue” 而不是 “HTML”）
另：保存时自动修复需开启 stylelint.autoFixOnSave，但要关掉编辑器内置的 CSS 格式化，否则冲突。
CI 报错本地正常？路径、语法、Node 版本三者最容易不一致
CI 失败而本地 OK，90% 是环境差异导致的配置未加载或解析失败。
排查重点：
-
npx stylelint命令里路径是否用了相对路径？CI 中工作目录可能不同，建议用绝对路径或"**/*.scss"这类 glob - CI 使用的 Node 版本是否支持你配置文件里的语法（比如
.mjs在旧版 Node 下不兼容） - 是否漏装
postcss-scss等依赖？CI 是 clean 环境，所有--save-dev依赖都得显式安装
真正麻烦的是规则本身没问题，但 customSyntax 加载失败或插件未声明——这种错误往往不报具体原因，只显示“no configuration found”。
