CSS变量在CSS Modules中无法局部化，必须挂载到组件根元素（如.button-root）上依赖继承生效，而非写在:root中；否则仍为全局作用域，导致跨组件覆盖。
CSS变量在CSS Modules里写:root声明，根本不会局部化——它还是全局的。想让变量随模块走，得把变量挂到组件根元素上，靠继承生效。
为什么:root里的CSS变量在.module.css中依然全局
CSS Modules只做一件事：把类名哈希化。它不碰--xxx自定义属性的作用域逻辑。浏览器看到:root { --color: red; }，不管这行代码在哪个.module.css文件里，都会把它塞进整个文档的根作用域。构建工具（比如css-loader）压根不解析或重写这些变量声明。
- 现象：改一个
Button.module.css里的--primary-color，所有用var(--primary-color)的地方全变了 - 根源：DOM树里只有一个
:root，和文件路径、模块名完全无关 - 验证方式：打开DevTools，在
Computed面板里查--primary-color，来源会显示:root，而不是某个组件类名
如何让CSS变量真正“属于”某个模块
关键不是“在哪写”，而是“绑定到谁身上”。必须把变量定义在组件容器选择器里，子元素靠CSS继承拿到值。
- 在
Button.module.css里写：.button-root { --button-bg: #007bff; }，而不是:root { --button-bg: ... } - 确保JSX中容器元素用了这个根类：
<div className={styles["button-root"]}>...</div> - 子元素样式直接用
background-color: var(--button-bg)，无需额外声明 - 多个
.button-root实例互不影响——每个都是独立变量作用域
和Ant Design等UI库一起用时的变量映射策略
Ant Design开启cssVar: true后，会往:root注入大量--ant-xxx变量。你自己的模块变量不能直接覆盖它们，但可以桥接：
立即学习“前端免费学习笔记（深入）”；
- 在组件根选择器里复用Ant Design变量：
.my-card { --card-bg: var(--ant-color-bg-container); } - 避免在
:root里重定义--ant-xxx，否则会污染全局；改用.my-component-root { --ant-color-bg-container: #f0f0f0; } - Umi项目中，若用
theme.config.ts配置了primary-color，它最终也转成:root变量——所以你的模块根选择器要显式覆盖：.my-btn { --ant-color-primary: var(--my-btn-primary, #1890ff); }
最容易被忽略的一点：CSS变量的继承链是“就近原则”，但它的生效依赖真实DOM结构。如果容器元素没渲染、被display: none掉，或者父级用了all: unset，变量就断了——这时候var(--x, fallback)的回退值反而成了救命稻草。
