React/Next.js/React Native中无法用全局样式覆盖CSS Module样式

核心问题原因 #

CSS Modules 生成的类选择器（比如编译后的.HelloWorld_Container_xxx）和全局类选择器（.danger-container）优先级相同，若组件样式在全局样式之后加载，组件默认样式就会覆盖全局类的样式。

方案1：用:where()降低组件默认样式优先级（最优） #

在组件的module.css中，用:where()包裹默认类选择器，它会将选择器优先级降为0，这样任何用户传入的全局类（优先级10）都能轻松覆盖：

/* HelloWorld.module.css */
:where(.Container) {
  background-color: green;
}

组件TSX代码保持不变：

// HelloWorld.tsx
import styles from './HelloWorld.module.css'

export default function HelloWorld({className}) {
    return <div className={`${styles.Container} ${className}`}>Hello world</div>;
}

用户传入danger-container后，红色背景会直接覆盖绿色，无需!important。

方案2：抽离可定制属性为CSS变量 #

将组件的可定制样式定义为CSS变量，用户可通过全局或局部样式覆盖变量值，这是组件库常用的灵活定制方案：

/* HelloWorld.module.css */
.Container {
  background-color: var(--hw-bg-color, green); /* 绿色为默认值 */
}

用户全局样式中覆盖变量：

/* global.css */
.danger-container {
  --hw-bg-color: red;
}

方案3：提供样式变体Props（组件库推荐） #

在组件中预设常用样式变体，比如variant属性，内部根据变体切换样式，同时保留className的扩展能力：

// HelloWorld.tsx
import styles from './HelloWorld.module.css'

type Props = {
  className?: string;
  variant?: 'default' | 'danger';
}

export default function HelloWorld({className, variant = 'default'}: Props) {
    const baseClass = variant === 'danger' ? styles.DangerContainer : styles.Container;
    return <div className={`${baseClass} ${className}`}>Hello world</div>;
}

/* HelloWorld.module.css */
.Container {
  background-color: green;
}
.DangerContainer {
  background-color: red;
}

用户使用时可直接传variant="danger"，也能结合className进一步定制：

<HelloWorld variant="danger" className="custom-padding" />

方案4：调整样式加载顺序（依赖用户配置） #

确保用户的全局样式在组件样式之后加载，这样全局类的样式会因“后定义”覆盖组件默认样式。但这种方式依赖用户的构建配置（如Vite/Webpack中的导入顺序），可靠性低，不推荐作为主要方案。

内容的提问来源于stack exchange，提问作者Tommy Wolfheart