Next.js CSS模块
Next.js CSS模块
介绍
Next.js CSS模块是Next.js框架提供的本地化样式解决方案，允许开发者创建组件级作用域的样式表。通过自动生成唯一的类名，CSS模块解决了传统CSS中全局命名冲突的问题，特别适合大型项目开发。
CSS模块的核心特性：
- 自动作用域：类名在构建时被转换为哈希字符串（如`_container_1x2yz_1`）
- 显式依赖：样式与组件文件显式关联
- CSS预处理器支持：原生支持Sass、Less等
- 开发体验优化：热重载保留组件状态
基本用法
创建模块
在组件同级目录创建.module.css后缀文件：
/* styles/Button.module.css */
.primary {
background: #0070f3;
padding: 8px 16px;
border-radius: 4px;
}
.size-large {
padding: 12px 24px;
}
组件中使用
通过对象语法引用类名：
// components/Button.js
import styles from './Button.module.css';
export default function Button({ size }) {
return (
<button
className={`${styles.primary} ${size === 'large' ? styles['size-large'] : ''}`}
>
Click Me
</button>
);
}
编译后生成的HTML示例：
<button class="_primary_1x2yz_1 _size-large_1x2yz_5">Click Me</button>
高级特性
组合类名
使用composes实现样式复用：
/* base.module.css */
.baseButton {
border: none;
cursor: pointer;
}
/* Button.module.css */
.primary {
composes: baseButton from './base.module.css';
background: blue;
}
动态类名
结合模板字符串实现条件样式：
<div className={`
${styles.card}
${isActive ? styles.active : ''}
${hasError ? styles.error : ''}
`}>
</div>
全局样式
通过:global包装全局类名：
:global(.reset-button) {
margin: 0;
padding: 0;
}
/* 组件内混合使用 */
.local {
composes: reset-button;
color: red;
}
架构原理
构建过程解析：
1. 解析阶段：Webpack识别.module.css文件
2. 转换阶段：CSS类名被替换为哈希值（如_button_1x2yz_1）
3. 映射生成：创建类名映射对象导出到JS
4. 运行时注入：样式被动态注入到<head>
性能优化
- 代码分割：CSS自动跟随组件懒加载
- 关键CSS：Next.js自动提取首屏关键样式
- 树摇优化：未使用的样式会被自动移除
- 缓存友好：哈希类名实现长期缓存
实际案例
主题切换实现
/* themes.module.css */
.light {
--bg: white;
--text: black;
}
.dark {
--bg: #222;
--text: #eee;
}
.container {
background: var(--bg);
color: var(--text);
transition: all 0.3s;
}
// ThemeSwitcher.js
import { useState } from 'react';
import styles from './themes.module.css';
export default function ThemeSwitcher() {
const [isDark, setIsDark] = useState(false);
return (
<div className={`${styles.container} ${isDark ? styles.dark : styles.light}`}>
<button onClick={() => setIsDark(!isDark)}>
Toggle Theme
</button>
</div>
);
}
最佳实践
1. 命名约定：使用BEM-like命名（如.header__title--active）
2. 组织方式：
* 每个组件对应一个模块文件
* 共享样式使用composes
3. 变量管理：
* 对于复杂主题使用CSS变量 * 避免在JS中硬编码样式值
4. 性能注意：
* 避免深层嵌套选择器（超过3层） * 关键路径组件避免复杂样式逻辑
与其他方案对比
| 特性 | CSS模块 | styled-jsx | Tailwind CSS |
|---|---|---|---|
| 作用域 | ✔️ 自动 | ✔️ 自动 | ❌ 需工具 |
| 可读性 | 高 | 中 | 低 |
| 学习曲线 | 低 | 中 | 高 |
| 运行时开销 | 无 | 极小 | 无 |
| 预处理器支持 | 完整 | 有限 | 不适用 |
常见问题
如何覆盖第三方组件样式？
使用:global包裹选择器：
:global(.third-party .item) {
padding: 0 !important;
}
类名映射如何工作？
构建时生成的JSON映射示例：
{
"button": "_button_1x2yz_1",
"active": "_active_1x2yz_5"
}
支持Sass/Less吗？
是的，只需安装对应处理器：
npm install sass # 或 less
然后创建.module.scss或.module.less文件
数学公式示例
CSS模块的类名生成算法可表示为： 其中：
filePath- 样式文件路径className- 原始类名salt- 构建配置的随机值