如何在 React 中通过 CSS 变量安全、可维护地定制 SCSS 组件样式

本文介绍一种比直接传递 `classnames` 更可靠的方式：利用 css 自定义属性（css variables）为可复用的 scss 组件提供主题化能力，解决深层嵌套选择器（如 `:hover`）无法被外部 `.module.scss` 类名覆盖的问题。

在 React 项目中使用 CSS Modules（如 .module.scss）时，一个常见误区是试图通过 className prop 向子组件“注入”外部样式类，期望它能穿透作用域影响深层嵌套元素（例如 的 :hover 状态）。但 CSS Modules 的局部作用域机制会阻止外部样式文件中定义的 .header .navBar .navButtons .navButton:hover 规则生效——因为 navButton 在 Header 组件内部已被编译为唯一哈希类名（如 navButton__abc123），而外部 SCSS 文件中写的 .navButton 并不匹配该哈希名。

✅ 正确解法：将可变样式抽象为 CSS 自定义属性（CSS Custom Properties），并在组件 SCSS 中通过 var() 函数消费它们。这种方式既保持了样式封装性，又提供了清晰、类型友好（可通过 CSS-in-JS 工具进一步强化）、可继承的定制接口。

以下是在 Header.module.scss 中的推荐实现：

// Header.module.scss
.header {
  // 定义私有变量（带下划线前缀表示内部使用）
  --_nav-item-color: var(--nav-item-color, #007bff);           // 默认主色
  --_nav-item-background: var(--nav-item-background, transparent);
  --_nav-item-hover-color: var(--nav-item-hover-color, #0056b3);
  --_nav-item-hover-background: var(--nav-item-hover-background, #f8f9fa);

  .navBar {
    // ... 其他基础样式
  }

  .navButtons {
    // ... 布局样式
  }

  .navButton {
    color: var(--_nav-item-color);
    background: var(--_nav-item-background);
    border: none;
    padding: 0.5rem 1rem;
    font-size: 1rem;
    cursor: pointer;
    transition: color 0.2s, background 0.2s;

    &:hover {
      color: var(--_nav-item-hover-color);
      background: var(--_nav-item-hover-background);
    }
  }
}

⚠️ 注意事项：

• 避免直接暴露 --_xxx 私有变量：命名以 --_ 开头表明其为内部实现细节，对外只承诺 --nav-item-* 等公共 API；
• 必须提供默认值：var(--nav-item-color, #007bff) 中的第二个参数确保即使未传入变量，组件仍可正常渲染；
• 无需修改 JS 逻辑：Header 组件本身无需改动，只需在使用处通过 className 设置含 CSS 变量的容器即可；
• 支持动态传入：也可结合 style prop 动态设置变量（适用于运行时主题切换）：

// LearnPage.tsx

// learn.module.scss
.specialHeader {
  --nav-item-hover-color: black;
  --nav-item-color: #096208;
}

? 进阶建议：

• 若项目规模较大，可配合 @layer（CSS Cascade Layers）或设计系统 Token 抽象（如 --color-primary, --color-accent）统一管理变量；
• 对于复杂交互状态（如 :focus-visible, :active），可按需扩展 --nav-item-focus-color 等变量；
• 使用 postcss-custom-properties 插件可为不支持 CSS 变量的旧浏览器提供降级 fallback（需谨慎评估必要性）。

这种基于 CSS 变量的设计模式，让 Header 真正成为一个「样式可配置」而非「样式可覆盖」的组件，兼顾了复用性、可维护性与现代 CSS 的表达力。