CSS自定义属性默认不被CSS Modules隔离，因为Modules仅对class/id选择器哈希重命名，而--变量声明本身属全局作用域，无论写在.module文件或普通CSS中，只要注入DOM即全局可见、可读、可覆盖。
为什么 CSS 自定义属性（CSS 变量）默认不被 CSS Modules 隔离
CSS Modules 只对 class 和 id 选择器做哈希重命名，而 --my-var 这类自定义属性声明本身是全局作用域的——无论写在 .module.scss 还是普通 .scss 里，只要被注入到 document 的样式表中，就可能被其他组件读取或覆盖。
这意味着：即使你用了 Button.module.scss，里面定义的 --button-color: red 仍可能被另一个组件的 :root { --button-color: blue } 覆盖，或者被 JS 通过 getComputedStyle 拿到并误用。
所以“安全隔离”不是靠文件名或 import 方式自动完成的，得靠命名约定 + 作用域约束 + 显式封装。
如何给 CSS 变量加“作用域前缀”避免冲突
最直接有效的方式是为所有自定义属性名加上组件级前缀，比如 --button-bg → --my-button-bg。这不是强制语法，但能从语义和工程实践上杜绝跨组件污染。
立即学习“前端免费学习笔记（深入）”；
- 前缀建议用组件名小写 + 连字符，如
--header-nav-item-color、--input-field-border-radius - 避免只用通用词如
--color、--size，哪怕加了:local()也无效——:local()不作用于变量声明 - SCSS 中可用变量辅助生成前缀：
$prefix: "my-button"; --#{$prefix}-bg: #007bff; - 别依赖
:global(--my-var)，它没意义——自定义属性天生全局，:global只影响选择器作用域
怎样让 CSS 变量真正“绑定到组件实例”
纯 CSS 无法做到变量实例级隔离，但可以通过组合策略逼近效果：用类名哈希 + 局部作用域选择器 + CSS 变量声明嵌套。
例如在 Button.module.scss 中：
.button {
--button-bg: #007bff;
--button-hover-bg: #0056b3;
}
.button:hover {
background-color: var(--button-hover-bg);
}
虽然 --button-bg 仍是全局变量，但它的使用被严格限制在 .button 及其后代选择器内；配合 CSS Modules 的类名哈希（如 .button__abc123），实际生效的变量作用域就被收束到该组件渲染出的 DOM 节点树中。
关键点：
- 永远把变量声明写在局部类选择器内部，而不是顶层（如
:root或空格开头的规则） - 不要在 JS 中通过
document.documentElement.style.setProperty设置同名变量——这会直接污染全局 - 若需动态更新，优先用
ref.current.style.setProperty作用于具体 DOM 节点
SCSS 中用私有变量 + CSS 变量双层封装更可控
在 .module.scss 文件里，可以用 SCSS 变量先定义值，再注入到带前缀的 CSS 变量中，既保留编译期控制力，又支持运行时覆盖。
例如：
$button-primary-color: #007bff;
$button-prefix: "my-button";
.my-button {
--#{$button-prefix}-bg: #{$button-primary-color};
--#{$button-prefix}-text: white;
background-color: var(--#{$button-prefix}-bg);
color: var(--#{$button-prefix}-text);
}
这样做的好处：
- SCSS 变量可被其他 SCSS 文件
@use复用，而 CSS 变量仍保持前缀隔离 - 外部可通过
style={{ '--my-button-bg': 'red' }}安全覆盖，不会影响其他组件 - 调试时浏览器开发者工具里能看到清晰的前缀，比哈希类名更易识别来源
真正容易被忽略的是：CSS 变量的“作用域”本质上是继承链 + 声明位置决定的，不是文件或模块决定的。哪怕你 import 了十个 .module.scss，只要它们都声明了 --theme-color，最后生效的永远是权重最高、位置最靠后的那一个——跟模块化没关系。所以前缀不是可选项，是必须项。
