安全更新组件级CSS变量须操作目标DOM节点style属性并设唯一data-id，用useEffect中ref.current.style.setProperty实现；变量需被var()消费且作用域匹配，SSR需:root兜底。
直接改 document.documentElement.style 会污染全局，所有组件都受影响；安全更新必须限定作用域，只操作目标 DOM 节点的 style 属性，并确保该节点有明确的作用域标识（如 data-id）。
用 ref + setProperty 更新组件级变量
React 不允许你在 render 阶段反复调用 DOM 方法，所以更新必须收束到 useEffect 或事件回调里。关键不是“能不能设”，而是“设给谁”。
- 给组件根元素加
ref，并在挂载后拿到真实 DOM 节点 - 调用
ref.current.style.setProperty('--color', '#333')，不是赋值对象 - 必须确保该元素有唯一
data-id（比如用useId()或随机字符串），否则变量没作用域约束，等于又回到全局 - 避免在
useMemo或render中重复调用setProperty，它不触发重排但会浪费 CPU
为什么 style={{ '--color': '#333' }} 有时不生效
这不是 React 的 bug，而是变量没被消费——CSS 变量本身不自动渲染任何样式，必须有对应 CSS 规则里写了 var(--color) 才起作用。
- 检查目标元素是否真的用了
color: var(--color)这类声明，而不是只在父级或兄弟节点里写 - 确认该元素是设置变量的那个节点的后代；变量不会跨兄弟、不会向上透传
- 如果用了
React.memo，确保style对象引用已变（推荐用useMemo(() => ({ '--color': value }), [value])） -
null或undefined值会被 React 完全跳过，别用color || ''，改用color ?? undefined
SSR 场景下首屏闪烁怎么防
服务端渲染时 JS 没执行，style 属性不会注入，浏览器先按无变量的 CSS 渲染，等 JS 加载后再 patch，就会闪一下。
立即学习“前端免费学习笔记（深入）”；
- 必须在 CSS 文件里为关键变量提供
:root兜底，例如:root { --color: #000; } - 或者在服务端提前注入带变量的
<style></style>标签（需配合renderToPipeableStream或框架 SSR 工具链） - 别依赖
getComputedStyle初始化状态，它在 SSR 中不可用，且在客户端频繁调用会强制重排 - 如果主题由
data-theme控制，记得在index.html的标签上预设该属性，让 CSS 能立刻生效
和 SCSS 混用时变量名容易冲突
SCSS 编译后是静态 CSS，它不知道你 JS 里设了什么变量；而 JS 设置的变量又只对后代生效。两者要协同，得靠命名隔离。
- 在 SCSS 里读变量时，一律用带下划线前缀的私有变量，比如
--_text-color - 定义时写成
--_text-color: var(--text-color, #333)，既回退到外部传入值，又 fallback 到默认色 - JS 端只设
--text-color，不碰--_text-color，避免覆盖 SCSS 的封装层 - 别在 SCSS 里直接写
var(--text-color)，除非你确定这个变量一定在祖先节点上声明过
最常被忽略的一点：CSS 变量不是状态同步机制，它只是样式传递通道。如果你在 JS 里改了变量，但组件逻辑还基于旧的 theme 值做判断，样式和行为就会脱节——变量更新 ≠ React 状态更新，该用 Context 的地方不能省。
