直接操作 className 会卡顿，因其触发全量 CSSOM 重建和重排重绘，且易被其他脚本覆盖；应改用 classList 增量操作，并用 data-theme 替代 class 控制主题。
为什么直接操作 document.documentElement.className 会卡顿
切换主题时用 className = 'theme-dark' 替换整个 class 列表，看似简单，但每次赋值都会触发浏览器重新解析全部 CSS 规则、重建 CSSOM、重排重绘——尤其当页面有大量 CSS 类或复杂选择器时，className 全量覆盖会让浏览器丢弃旧的 class 缓存，无法复用已计算的样式匹配结果。
更麻烦的是，如果其他脚本（比如框架、统计 SDK）也在读写 className，就可能相互覆盖、丢失 class，导致主题失效或样式错乱。
- 避免全量赋值：改用
classList.add()/classList.remove()增量更新 - 不要依赖 class 名做主题判断逻辑（如
if (body.className.includes('dark'))），改用dataset或自定义属性 - 若必须用 class 控制主题，确保只写一个主题类（如
theme-dark），不混入功能类（如is-loaded）
document.documentElement.setAttribute('data-theme', ...) 的真实开销在哪
用 data-theme 属性触发 CSS 变量重写，本身几乎无性能损耗——它只是修改一个 HTML 属性，不触发 layout 或 paint。但真正耗时的环节藏在后面：[data-theme="dark"] :root 这类嵌套选择器会让浏览器对每个 :root 节点都做属性匹配，且需重新计算所有依赖该变量的样式声明。
实测发现，当变量超过 30 个、CSS 文件体积超 150KB 时，首次切换会有明显延迟（尤其低端 Android 设备）。
立即学习“前端免费学习笔记（深入）”；
- 精简变量数量：把语义相近的变量合并（如
--border-color和--divider-color统一为--border-divider-color） - 避免深层嵌套选择器：不用
[data-theme="dark"] .container :root，只用[data-theme="dark"] :root - 变量名别带空格或特殊字符：CSS 变量名只认字母、数字、连字符，
--bg color是无效的
用 style.setProperty() 直接改变量，为什么有时不生效
常见错误是写成 document.body.style.setProperty('--bg-color', '#000')——这完全无效，因为 --bg-color 必须在 :root 作用域下定义并修改，body.style 的作用域仅限于 body 元素自身及其继承链，无法影响全局变量。
另一个坑是：JS 修改后立即读取 getComputedStyle(document.documentElement).getPropertyValue('--bg-color')，可能拿到旧值。这是因为变量更新是异步应用的，不是同步反射。
- 务必用
document.documentElement.style.setProperty() - 需要读取新值时，加
requestAnimationFrame确保样式已更新 - 批量修改多个变量时，别逐个调用
setProperty，先缓存再统一设置（减少 style 对象访问次数）
localStorage + 首屏闪屏问题的本质和绕过方式
闪屏不是 JS 慢，而是浏览器渲染流程决定的：HTML 解析完、CSS 加载完、首次样式计算完成，就立刻绘制；此时 JS 还没执行，localStorage 里的主题设置根本没机会生效。
服务端渲染或 SSR 不是唯一解。更轻量的做法是在 <html> 标签上预埋属性：<html data-theme="dark">，靠服务端模板或构建时注入，让 CSS 从第一帧就按正确主题渲染。
- 不要等
DOMContentLoaded再读localStorage，那已经晚了 - 如果必须客户端处理，用内联
<script>放在<head>最前，同步读取并设置data-theme - 注意 Safari 对
localStorage的同步读取限制（某些隐私模式下会抛异常），要加try/catch
