Vite项目中CSS样式冲突的根本原因是CSS Modules未真正生效，需从文件命名（严格.module.css格式）、导入方式（禁用@import全局CSS）、构建配置（确认css.modules未设为false）三方面同时解决。
在Vite项目中，多个组件的样式类名相同（如都用.btn）导致互相覆盖、按钮变圆、文字颜色丢失，根本原因不是类名写重了，而是CSS Modules没真正生效或被绕过，必须从文件命名、导入方式、构建配置三处同时卡死。
确认模块化是否真启用
第一步：打开终端，执行npm run build后检查dist/assets目录下生成的CSS文件内容。如果看到.btn原样存在，没变成类似Button__btn___a1b2c3d4的哈希形式，说明模块化根本没触发。
第二步：检查文件名是否严格符合.module.css（或.module.scss/.module.less）格式——【大小写敏感，缺一个字符都不行】。常见错误：button.module.CSS（大写）、Button.Module.css（Module首字母大写）、style.module（缺后缀）。
第三步：确认vite.config.js里没有显式关闭模块化，比如写了css: { modules: false }。Vite默认开启，但一旦手动设为false，所有.module.*文件都会退化为普通CSS。
立即学习“前端免费学习笔记（深入）”；
命名规范：从源头掐断冲突可能
方法一：强制带组件名前缀（推荐）
不写.btn，改写为.Button-primary、.Card-header。这不是BEM风格建议，而是让generateScopedName生成的哈希名天然携带语义，比如Button__primary___x7y8z9和Modal__primary___m2n3o4完全不会撞车。
方法二：禁用驼峰转换，保留连字符可读性
在vite.config.js中设置localsConvention: 'dashes'，这样.card-header导入后仍是styles['card-header']，避免因驼峰转换出错导致styles.cardHeader返回undefined。
方法三：用composes复用而非复制
在Filter.module.css里写.filter-btn { composes: btn from '../Base.module.css'; }，既复用基础样式，又确保filter-btn和btn各自哈希隔离——【千万别用@import './Base.css'，它会把Base.css以全局方式注入】。
处理已存在的全局样式冲突
① 找出冲突源：打开浏览器开发者工具，选中异常元素，在Styles面板里逐条点击右侧CSS规则，看哪条被划掉（strikethrough）。被划掉的那条就是被更高权重规则覆盖的。
② 提升局部权重：在Button.module.scss中，不用.btn { ... }，改写为.btn.btn { ... }（双重类名），权重翻倍，轻松压过全局.btn。
③ 锁定全局作用域：把所有第三方库或重置样式（reset.css、normalize.css）统一放在src/styles/global/下，并只在main.jsx最顶部导入一次。其他任何地方禁止@import或import全局CSS文件。
④ 需要穿透时，精确包裹：写:global(.ant-btn) { color: red; }，而不是:global(.ant-btn) .icon——后者会让.icon失去局部化，变成全局污染点。
