CSS【模块】CSS Modules

你想要学习 CSS 模块（CSS Modules）的使用方法，这是一种解决 CSS 作用域冲突、让样式模块化的主流方案，尤其在 React、Vue 等前端框架中应用广泛。我会从基础概念到实际应用，一步步带你掌握 CSS 模块。

什么是 CSS 模块？

CSS 模块本质上是一个文件级别的作用域隔离方案：

默认情况下，CSS 的样式是全局生效的，多个文件中同名的类名会互相覆盖，这是前端样式冲突的核心原因。
CSS 模块会将每个 CSS 文件中的类名、动画名等编译成唯一的哈希值 （比如 .header 变成 .header_3zyde4），让每个样式只作用于当前模块，彻底解决全局冲突。
它不是新的语法，而是一种构建工具（Webpack/Vite）的处理方式，最终输出的还是普通 CSS。

实战范例

以 Vite + React 为例，Vite 内置支持 CSS 模块，无需额外配置

1. 创建 CSS 模块文件

CSS 模块文件必须以 .module.css 为后缀（Vue 中是 .module.vue 或 .module.css）

这是一个约定俗成的写法。只要用了 .module.css 这个后缀，Webpack、Vite 这些构建工具就会自动识别，帮我们把类名改成独一无二的哈希值。

如果你用的是 Sass 或 Less，只要把后缀改成 .module.scss 或 .module.less 即可

css 复制代码

/* 文件名 Product.module.css */
.productTitle {
  font-size: 2rem;
  font-weight: 700;
}

样式名建议用驼峰命名

2. 导入CSS 模块文件

js 复制代码

import styles from "./Product.module.css";

3. 使用

html 复制代码

<div className={styles.productTitle}>iPad Pro</div>

如果css样式名中出现了连字符"-"、或者其他特殊的、不符合js变量命名规范的字符，就必须使用方括号[]并配合引号""使用（如下方范例），所以样式名建议用驼峰命名

js 复制代码

<div className={styles["product-title"]}>iPad Pro</div>

更多用法

组合多个类名

html 复制代码

<div className={`${styles.box} ${styles.highlight}`}>...</div>

全局样式

用 :global()包裹

css 复制代码

:global(.reset) { margin: 0; }

使用全局样式（直接写类名，无需 styles.）

c 复制代码

<p className="reset">这是全局样式的文本</p>

组合样式

通过 composes 复用其他类名样式

css 复制代码

/* App.module.css */
.title {
  color: #2c3e50;
  font-size: 24px;
  text-align: center;
}

/* 样式组合（复用其他类名） */
.boldTitle {
  composes: title; /* 复用 title 的样式 */
  font-weight: 700;
  color: #e74c3c;
}

跨文件复用样式：

css 复制代码

/* common.module.css */
.flex {
  display: flex;
  justify-content: center;
  align-items: center;
}

/* App.module.css */
.box {
  composes: flex from './common.module.css'; /* 复用 common 中的 flex 样式 */
  width: 200px;
  height: 200px;
  border: 1px solid #ccc;
}

适用场景

组件化开发的框架项目（React/Vue）、多人协作的大型项目、需要低成本样式隔离的场景；

不适用场景

纯静态页面、全局基础样式、已用 scoped/CSS-in-JS 的项目、无构建工具的原生项目；

Vue 中如果用 <style scoped>，已经实现了组件样式隔离，无需再用 CSS 模块（两者选其一即可，不建议叠加）。