批量更新CSS变量应一次性传入对象调用setCssVars，作用域必须为document.documentElement，清除需用removeProperty而非设空，SSR需HTML预设默认值并配合@supports降级。
直接用 setProperty 逐个设太慢，批量更新要合并调用
单次 setProperty 只改一个变量，频繁调用 JS Interop 或反复触发 style 更新会明显卡顿。真正批量更新不是循环调用 setProperty，而是把多个变量打包成一个对象，一次性传给 JS 函数处理。
- 在
wwwroot/js/site.js里定义统一入口：window.setCssVars = (vars) => { const root = document.documentElement; Object.entries(vars).forEach(([name, value]) => { root.style.setProperty(name, value); }); }; - Blazor 中调用：
await JSRuntime.InvokeVoidAsync("setCssVars", new Dictionary<string string> { ["--primary-color", "#ef4444"], ["--font-size", "18px"] });</string> - JS 原生环境同理，别写 for 循环调
setProperty，先收集再统一设
全局变量必须挂到 document.documentElement，别错写成 body 或其他元素
CSS 变量靠继承生效，:root 对应的就是 document.documentElement（即 <html> 元素）。写到 document.body 或任意 div 上，变量只在该元素及其后代里有效，根本达不到“全局”效果。
- 错误写法：
document.body.style.setProperty('--color', 'red')→ 页面大部分区域不响应 - 正确写法：
document.documentElement.style.setProperty('--color', 'red') - 注意前缀：变量名必须带双破折号，
--color不能写成color或color-primary
设空字符串或 undefined 不等于删除，真要清除得用 removeProperty
setProperty('--size', '') 或 setProperty('--size', undefined) 不会删掉变量，只会让它的值变成无效（浏览器计算时返回 initial 或默认值），但变量依然存在于 style 对象里，可能干扰后续逻辑。
- 想彻底移除变量，必须用：
document.documentElement.style.removeProperty('--size') - 批量清除？同样建议封装：
window.removeCssVars = (names) => { const root = document.documentElement; names.forEach(name => root.style.removeProperty(name)); }; - 注意：
removeProperty不会触发 CSS 重计算，但变量没了，依赖它的样式自然回退到 fallback 值（如var(--size, 16px)中的16px）
SSR 场景下首次渲染没变量，必须 HTML 预设 + @supports 降级
服务端渲染时，JS 还没执行，document.documentElement.style 是空的，用户看到的是无变量状态。单纯靠 JS 设置无法补救首屏。
立即学习“前端免费学习笔记（深入）”；
- HTML 模板里提前写死默认值：
<html style="--primary-color: #3b82f6; --spacing: 1rem;">
- CSS 中加
@supports (--css: 0)包裹变量使用区，让不支持自定义属性的老浏览器走备用规则 - Blazor Server 模式下，JS Interop 在首屏后才可用，变量切换必须配合
StateHasChanged()同步 C# 状态，否则 UI 不感知变化
批量更新的核心不在“多”，而在“一次到位”。变量名拼错、作用域写错、SSR 缺默认值，这三处出问题，哪怕代码跑通也看不到效果。
