CSS Modules实战指南：告别样式冲突提升组件可维护性

我的写法，亲测靠谱

在用 CSS Modules 的这几年里，我折腾过好几种写法，最后稳定下来的这套方案，是踩了无数坑后总结出来的。核心就一点：类名尽量语义化，但别过度设计；结构清晰，但别搞复杂。

我现在的习惯是：一个组件对应一个 .module.css 文件，文件名和组件名一致。比如 Button.jsx 就配 Button.module.css。这样找起来快，维护也省心。

样式命名上，我不再用 BEM 那套长到离谱的写法（比如 button__icon--disabled），而是直接用简洁的单词组合。因为 CSS Modules 本身已经做了作用域隔离，不需要靠命名规范防冲突了。下面是我现在常用的写法：

/* Button.module.css */
.root {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  padding: 8px 16px;
  border-radius: 4px;
  font-size: 14px;
  cursor: pointer;
  transition: background 0.2s;
}

.primary {
  background: #1890ff;
  color: white;
}

.disabled {
  opacity: 0.5;
  pointer-events: none;
}

.icon {
  margin-right: 6px;
}

对应的 JSX：

import styles from './Button.module.css';

export default function Button({ variant = 'primary', disabled, icon, children }) {
  const cls = [
    styles.root,
    styles[variant],
    disabled && styles.disabled
  ].filter(Boolean).join(' ');

  return (
    <button className={cls} disabled={disabled}>
      {icon && <span className={styles.icon}>{icon}</span>}
      {children}
    </button>
  );
}

这种写法的好处很明显：逻辑清晰、扩展性强。加个 secondary 变体？直接在 CSS 里加个 .secondary 类就行，JSX 一行都不用动。而且因为用了 filter(Boolean)，不用担心 undefined 混进 class 字符串里。

有人可能会说“为什么不直接用 clsx 或 classnames”？我试过，但在小项目里引入额外依赖不值当，自己写个数组过滤更轻量。大项目如果已经装了，当然可以用，但别为了这点便利把构建搞复杂。

这几种错误写法，别再踩坑了

我见过太多人把 CSS Modules 用歪了，下面这几个反面案例，你很可能正在犯：

• 滥用全局样式：为了“方便”，在 module 文件里写 :global(.some-class)，结果又回到了全局污染的老路。CSS Modules 的核心价值就是局部作用域，你把它绕过去，等于白用。
• 类名拼接字符串：比如 className={${styles.btn} ${styles[props.type]}}。看起来没问题？但如果 props.type 是空或者非法值，就会生成类似 btn undefined 的 class，虽然不影响功能，但 DOM 看着难受，调试时容易误判。
• 嵌套太深：有人喜欢写：

  .container {
        .header {
          .title { ... }
        }
      }

  然后在 JS 里用 styles.container_header_title。这完全违背了 CSS Modules 的初衷！模块化不是让你模拟 Sass 嵌套，而是扁平化管理。嵌套越深，类名越难读，还容易引发命名冲突（虽然概率低）。

• 动态拼接类名：比如 styles[btn-${size}]。这种写法在开发环境可能跑得通，但很多构建工具（特别是老版本 Webpack）无法静态分析这种动态 key，导致类名没被正确导出，最后样式丢失。我之前在一个项目里折腾半天才发现是这个问题。

记住：CSS Modules 的类名必须是静态的、可被构建工具识别的字符串字面量。别图一时爽，后面 debug 到凌晨。

实际项目中的坑

除了写法问题，实际项目里还有几个容易忽略的细节：

1. 第三方组件库的样式覆盖

你想覆盖 Ant Design 或 Element UI 的样式？别直接在 module 文件里写 :global。更好的做法是：在全局样式文件（比如 global.css）里覆盖，或者用更高优先级的选择器。如果你非要在组件内覆盖，至少把 :global 限制在最小范围：

/* 不推荐 */
:global(.ant-btn-primary) {
  background: red;
}

/* 推荐：限定在当前组件根元素下 */
.wrapper :global(.ant-btn-primary) {
  background: red;
}

然后在组件最外层加上 className={styles.wrapper}。这样至少不会污染其他地方。

2. 动画 keyframes 的处理

CSS Modules 对 @keyframes 也会哈希化，所以如果你这样写：

@keyframes slideIn {
  from { transform: translateX(-100%); }
  to { transform: translateX(0); }
}

.animate {
  animation: slideIn 0.3s ease-out;
}

实际生成的可能是 animation: SlideIn_xyz123 0.3s...，而 slideIn 这个名字已经被替换了。所以动画照样跑，没问题。但如果你在 JS 里动态设置 animation name（比如通过 style 属性），那就麻烦了——你不知道编译后的名字是什么。

我的建议是：别在 JS 里操作 animation name，全交给 CSS 控制。需要开关动画？用 class 切换，别用 inline style。

3. SSR 场景下的类名一致性

如果你用 Next.js 或 Gatsby 做服务端渲染，确保客户端和服务端生成的 CSS 类名一致。一般只要构建配置正确（比如 Webpack 的 localIdentName 在 dev 和 prod 保持一致），就不会出问题。但我曾经在一个老项目里，因为 dev 环境用了 [name]__[local]___[hash:base64:5] 而 prod 用了 [hash:base64:5]，导致 hydration 报错。排查了整整一下午……

解决方案很简单：统一配置。比如在 Webpack 中：

{
  loader: 'css-loader',
  options: {
    modules: {
      localIdentName: '[hash:base64:6]' // dev 和 prod 都用这个
    }
  }
}

结尾碎碎念

其实 CSS Modules 没什么高深的，核心思想就一个：让 CSS 也像 JS 模块一样，按需引入、作用域隔离。但很多人用着用着又回到全局样式的老路上，要么是惯性思维，要么是图省事。

我的经验是：前期多花十分钟规范写法，后期能省几十小时 debug 时间。特别是在团队协作时，统一的 CSS Modules 规范比任何文档都管用。

以上是我踩坑后的总结，希望对你有帮助。有更好的方案欢迎评论区交流——比如你怎么处理主题切换？怎么和 Tailwind 混用？这些我也还在摸索中。