vite对css modules开箱即用，只需文件名含.module.css等后缀即自动启用模块化；修改vite.config.js通常不必要，除非需定制类名格式、解决特殊冲突或适配微前端。
为什么改 vite.config.js 通常没必要
Vite 对 CSS Modules 是开箱即用的，只要文件名带 .module.css（或 .module.scss、.module.less 等），就自动启用模块化逻辑，无需任何配置。你改 vite.config.js 的默认导出，大概率不会让样式更“隔离”，反而可能覆盖默认行为导致类名不哈希、或哈希格式异常。
css.modules 配置项只在需要定制时才动
只有当你明确要调整生成的类名格式、解决特殊冲突（比如和 @scope 规则打架）、或配合微前端插件（如 vite-plugin-federation）时，才需要显式配置 css.modules。常见修改点包括：
- 改哈希长度：
generateScopedName: '[name]__[local]___[hash:base64:5]'（默认就是这个，一般不用动） - 加前缀避免和第三方库类名偶然重叠：
generateScopedName: 'prefix_[name]__[local]___[hash:base64:4]' - 禁用局部作用域（极少用）：
modules: false—— 这会让.module.css文件也当全局处理，直接放弃模块化
注意：css.modules 是对象，不是布尔值；写成 modules: true 会报错，Vite 不认。
真正该检查的三个地方
类名冲突往往不是配置问题，而是使用姿势不对。优先排查以下三项：
-
文件名是否带
.module后缀：写成Button.css就是全局；必须是Button.module.css，否则import styles from './Button.css'导出的是空对象 -
是否误用了
@import：在.module.css里@import './global.css'会把全局样式注入到模块作用域，破坏隔离；要用:global(.xxx)显式穿透 -
是否动态拼接类名：写
className={styles.btn + ' other-class'}会导致other-class脱离模块控制，变成全局污染源；应全量走styles对象，或用clsx等工具安全组合
遇到 @scope 或构建后样式错乱怎么办
Vite 当前对 CSS @scope 规则的支持不稳定，尤其和 Sass/Less 混用时，容易出现开发正常、打包后类名混淆或样式丢失。这不是配置能绕过的，建议：
- 暂时回避
@scope，改用composes复用或父级嵌套提升权重 - 如果必须用，先在
vite.config.js中收紧哈希规则：generateScopedName: '[local]_[hash:base64:4]'，缩短哈希避免过长截断 - 确认构建产物中对应 CSS 文件是否真的被当作模块处理（查看 dist 下文件名和内容里是否有哈希类名）
最常被忽略的一点：CSS Modules 的隔离能力只存在于构建时，它不运行时注入、不操作 DOM、也不拦截 style 属性——所有效果都靠「文件名约定 + 构建重命名」完成，漏掉任何一个环节，隔离就失效。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
