Stylelint 通过 husky + lint-staged 在 Git 提交前拦截不合规 CSS，仅检查变更文件；需配置 .stylelintrc.cjs 统一规则、注意 customSyntax 和 ignoreFiles、确保 CI 与本地 Node 版本及依赖一致。
Stylelint 本身不提供“强制执行”的能力，它只是个静态检查工具；真正能强制的，是把它接入 CI 流程或编辑器保存时自动修复 + 提交前校验。
怎么让 Stylelint 在 Git 提交前拦住不合规的 CSS？
靠 husky + lint-staged 组合实现提交拦截。只检查本次修改的 CSS/SCSS 文件，避免全量扫描拖慢体验。
- 安装依赖：
npm install -D husky lint-staged stylelint - 初始化 husky：
npx husky install，然后添加 pre-commit 钩子：npx husky add .husky/pre-commit "npx lint-staged" - 在
package.json中配置lint-staged，指定对*.{css,scss,less}执行stylelint --fix，失败则中断提交 - 注意：如果团队用 VS Code，建议同步配
stylelint.vscode-stylelint插件，保存时自动 fix，减少提交时被拦住的次数
为什么团队共用的配置不能直接 npm install stylelint-config-standard？
因为 stylelint-config-standard 默认启用所有规则，而实际项目常需调整——比如允许单引号、禁用 color-no-hex、适配 CSS-in-JS 的属性写法。
- 推荐做法：新建
.stylelintrc.cjs，export default一个对象，extends基础配置（如stylelint-config-standard），再用rules覆盖具体项 - 关键点：把配置文件加入 Git，而不是靠每个成员手动安装某 preset；否则有人漏装，CI 就会报错
- 常见坑：
overrides段落里匹配**/*.module.css时，必须显式设置customSyntax: 'postcss-css-in-js'，否则解析失败报Unknown word
CI 环境下 Stylelint 报错但本地不报，怎么回事？
大概率是 Node 版本或依赖解析路径不一致，尤其涉及插件（如 stylelint-scss）时。
立即学习“前端免费学习笔记（深入）”；
- 检查 CI 使用的 Node 版本是否与本地一致（
node -v），不同版本可能导致peerDependencies解析差异 - 确保
stylelint和所有插件都列为devDependencies，而非dependencies；否则某些 CI 环境（如设置了--production）会跳过安装 - 运行命令统一用
npx stylelint "**/*.{css,scss}" --max-warnings 0，--max-warnings 0是关键——否则警告不阻断 CI - 如果用了自定义语法（如
stylelint-config-html），CI 中需额外安装对应postcss-html，且customSyntax字符串必须完全匹配包名
最易被忽略的是 ignoreFiles 配置：.stylelintrc 里的 ignoreFiles 只作用于 CLI 扫描路径，不影响编辑器插件；团队若用 Storybook 或构建产物生成 CSS，得单独在 .stylelintignore 里声明，否则 CI 会扫到不该扫的文件并报错。
