在团队开发中如何使用Stylelint工具强制执行CSS代码规范

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 会扫到不该扫的文件并报错。