文件名必须为Button.module.scss,且需import styles from './Button.module.scss'并用styles.className访问;否则样式全局污染或失效。

文件名必须带 .module.scss 后缀
Webpack(含 CRA、Vite、Next.js)只对 .module.scss 文件启用 CSS Modules 逻辑。写成 Button.scss 或 Button.css,哪怕内容完全一样,也会被当作全局样式注入 ,导致类名裸奔、样式污染。
常见错误现象:
-
import './Button.scss'→ 样式全局生效,.btn在整个页面都起作用 -
import styles from './Button.module.css'→ 虽然模块化,但失去 SCSS 嵌套、@mixin、变量等能力 -
import styles from './Button.scss'+className={styles.btn}→styles是 undefined,运行时报错或无样式
正确做法只有一条:文件名严格为 Button.module.scss,且导入必须是 import styles from './Button.module.scss'。
className 必须通过 styles.xxx 访问
CSS Modules 会把 .container 编译成类似 container__abc123 的哈希名,这个映射只存在于 JS 对象中。直接写字符串类名,DOM 上就是原始名,浏览器找不到对应规则。
容易踩的坑:
-
className="container"→ 失效,不匹配哈希类 -
import * as styles from './Dashboard.module.scss'→ 错误导入方式,styles是默认导出对象,不是命名空间 -
className={styles['container-' + size]}→ 动态键名在编译期不存在,结果是undefined
正确写法示例:
Lightning CSS 是由 Parcel 团队开发的基于 Rust 的 CSS 解析器、转换器、打包工具和压缩工具。此技能适用于需要优化样式表、为目标浏览器降低现代 CSS 语法以及将快速 CSS 处理集成到构建或重构工作流中的代理。
import styles from './Dashboard.module.scss';
<p>function Dashboard() {
return </p><div classname="{styles.container}"></div>;
}
SCSS 嵌套和变量可用,但作用域仅限最外层
.container { .item { } } 这类嵌套语法照常工作,但 CSS Modules 只会对最外层选择器(.container)加哈希;内部的 .item 不单独哈希,而是依赖父级生成的类名,最终输出类似 container__abc123 .item。
这意味着:
- 可以正常使用
$primary-color: #007bff和@mixin flex-center,只要构建链有sass-loader - 想复用其他模块的样式?不行。
styles对象只包含当前文件定义的类,跨文件引用需显式导入另一个xxx.module.scss - 需要同时用局部类和全局动画类?拼接字符串安全:
className={`${styles.card} animate fadeIn`},但确保animate已全局引入
伪类、响应式、主题切换要靠 CSS 变量驱动
单纯靠 styles.button + styles['button--large'] 难以覆盖 :hover、@media 或暗色模式逻辑。更可靠的做法是在 .module.scss 中定义私有 CSS 变量,并用 var(--_hover-bg, #f0f0f0) 调用:
.button {
--_bg: var(--button-bg, #007bff);
--_hover-bg: var(--button-hover-bg, #0056b3);
background: var(--_bg);
&:hover {
background: var(--_hover-bg);
}
}
这样外部可通过 style={{ '--button-bg': '#ff6b35' }} 或全局 CSS 变量注入定制,无需破坏模块封装。
真正难处理的是嵌套层级过深时的哈希传播、@use partial 文件热更新失效、以及路径别名(如 @/styles)未被 Sass 解析——这些细节不报错,但会让样式“看起来没变”,调试起来最耗时间。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!










