vite 仅通过文件名后缀（如 .module.css）启用 css modules，非标准命名将导致样式全局污染或导入失败；必须用 styles.xxx 绑定类名，第三方样式需 :global() 显式透出；less 需额外配置或改用 .module.scss/.module.css。
文件名必须带 .module.css 后缀才触发模块化
Vite 默认只对 .module.css、.module.scss、.module.less 这类后缀启用 CSS Modules，不是靠配置开关，而是靠文件名硬匹配。一旦写成 Button.css 或 button.Module.scss（大小写错）、styles.module（缺后缀），Vite 就当普通 CSS 处理，类名原样输出，冲突立刻发生。
常见错误：
-
import './Button.css'→ styles 是空对象，styles.btn为undefined - 在 macOS/Linux 下路径写成
./button.module.css（小写），但文件实际是Button.module.css（首字母大写）→ 导入失败 - 用 VS Code 自动导入功能，它可能推荐
Button.css而非Button.module.css，需手动核对
导入后必须用 styles.xxx 动态绑定类名
CSS Modules 导出的是一个 JS 对象，比如 { btn: 'Button__btn___a1b2c3d4', disabled: 'Button__disabled___e5f6g7h8' }。你不能跳过映射直接写字符串。
正确做法：
import styles from './Button.module.css'<button classname="{styles.btn}">Click</button>
错误写法：
-
<button classname="btn">Click</button>→ 样式不生效，且“btn”以全局形式注入，可能覆盖其他组件 -
className={`${styles.btn} extra-class`}→extra-class不走模块化，变成全局污染源 -
require('./Button.module.css')→ 返回结构不同，styles.btn可能为undefined
第三方样式或重置必须用 :global() 显式透出
CSS Modules 默认只作用于当前模块内的类选择器。想复用 highlight.js 的 .hljs、Ant Design 的 .ant-btn，或重置 html、body，必须包裹 :global()。
示例：
.normal { color: red; }
:global(.hljs) { background: #2d2d2d; }
:global(html, body) { margin: 0; }
漏掉 :global() 的后果：
-
.hljs规则被忽略，语法高亮失效 -
html, body { margin: 0 }不生效，页面出现默认外边距 - Vue 单文件组件中
<style scoped></style>和<style module></style>都需要同样处理
Less 文件默认不走 CSS Modules 流程
.less 文件即使改名为 Button.module.less，Vite 也不会自动启用模块化——它只认 .module.css 和 .module.scss。Less 需要额外 loader 链路支持，否则类名照常全局输出。
务实解法：
- 直接切到
.module.scss或.module.css，让 CSS Modules 原生接管 - 若必须用 Less，最外层加唯一根类：
.Button { .btn { } }，靠 DOM 作用域隔离 - 用 PostCSS 插件如
postcss-prefixwrap编译后自动加前缀：[data-scope="Button"] .btn -
composes是 CSS Modules 语法，Less 解析器不认识，写进去直接报错
真正容易被忽略的点：BEM 类名（如 button__icon）不是为了取悦构建工具，而是给人看的。文件名、目录结构、类名三者必须一致 —— components/Button/Button.module.css 里只允许出现 button、button__*、button--* 开头的类。打破这个约束，哈希再唯一，协作也难推进。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
