css modules 不支持跨文件 css 变量注入，因 :root 被局部作用域化；需用 :global() 引入全局变量或构建时注入主题变量。
React 中 CSS Modules 本身不支持 CSS 变量的跨文件注入或主题切换——它只做类名哈希化和作用域隔离，:root 或 @import 进来的变量不会自动随主题文件替换。真要实现主题化，得靠构建时变量注入 + CSS Modules 配合，而不是仅靠 import styles from './Button.module.css' 就完事。
为什么直接在 .module.css 里用 :root 变量会失效
CSS Modules 对每个 .module.css 文件单独作用域处理，:root 声明会被包裹进该文件生成的唯一类名作用域内（比如 .Button_root__abc123），不再等价于全局文档根节点。结果就是：
- 变量无法被其他模块读取，
var(--primary-color)在 Button.module.css 里可能始终是 undefined - 即使你手动在
index.html的<style></style>里写了:root { --primary-color: blue; }，CSS Modules 编译后生成的选择器优先级或作用域限制也可能导致它不生效 - 热更新时变量值不会刷新，改了主题配置但样式没变，容易误判为代码写错
用 CSS Custom Properties + :global() 注入主题变量
可行路径是：把主题变量定义在全局 CSS 中，再在 .module.css 里通过 :global() 显式引用，绕过作用域限制。
例如：
/* themes/dark.css */
:root {
--bg-color: #1e1e1e;
--text-color: #f0f0f0;
}
然后在组件中：
/* Button.module.css */
.button {
background-color: var(--bg-color);
color: var(--text-color);
}
<p>/<em> 必须加 :global() 才能访问上面定义的 :root </em>/
:global(:root) .button {
/<em> 此处只是确保作用域穿透，实际不用写规则 </em>/
}
</p>
关键点：
- 必须先
import './themes/dark.css'（非 module 后缀），让变量注入 -
.module.css中不能写:root { ... }，只能用var(--xxx)+ 确保外部已定义 - 多个主题切换时，用 JS 动态替换
document.documentElement.style.setProperty()比重载 CSS 文件更轻量
配合 webpack / Vite 实现构建时变量替换
如果主题是编译期确定的（如打包出 dark/light 两个版本），可用构建工具注入常量：
- Vite：在
vite.config.ts中用define注入process.env.THEME，再配合css.preprocessorOptions.scss的additionalData插入变量声明 - webpack：用
DefinePlugin+css-loader的modules.compileType = 'icss'支持@value语法（需搭配postcss-modules-values） - 注意：
@value primary-color from './colors.css'这类写法在标准 CSS Modules 下不被支持，必须启用 icss 模式且配置 loader
示例（Vite）：
// vite.config.ts
export default defineConfig({
define: {
__THEME__: JSON.stringify('dark')
},
css: {
preprocessorOptions: {
scss: {
additionalData: `@use "./src/themes/${process.env.NODE_ENV === 'production' ? 'dark' : 'light'}.scss" as *;`
}
}
}
})
别把主题逻辑塞进 CSS Modules 类名里
常见误区是试图用 styles['button--' + theme] 这种方式动态拼类名来切换主题。这行不通，因为：
-
button--dark不在styles对象里，除非你在.module.css中明确定义了该类 - 主题变更时，JS 层需同步触发重渲染，而 CSS Modules 不提供响应式变量监听机制
- 最终还是得回到 CSS 变量或 className 切换，不如一开始就用
className={\`button \${theme === 'dark' ? 'dark' : 'light'}\`}+ 全局 CSS
真正可维护的主题方案，核心不在 CSS Modules 本身，而在变量注入时机和作用域穿透控制——:global() 不是 hack，而是必要手段；构建时替换不是银弹，但适合多版本发布场景。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
