CSS主题按需加载应动态创建link标签并移除旧样式，同步用data-theme切换CSS变量块，主题类加在html上并提供降级值，避免布局抖动。
主题 CSS 文件如何按需加载不阻塞渲染
直接在 <head> 里写多个 <link rel="stylesheet"> 并用 disabled 控制开关，看似简单，但会导致所有 CSS 文件仍被预加载、解析甚至触发 FOUC 风险。真正按需应只让当前主题的样式表处于 disabled=false 状态，其余完全不插入 DOM。
- 优先使用
document.createElement('link')+rel="stylesheet"动态创建，而非提前写死全部 link 标签 - 切换前先调用
linkElement.remove()清除旧主题，再 append 新 link，避免残留规则干扰 - 新 link 插入后监听
link.onload再触发 class 切换，防止样式未就绪时 DOM 已应用新主题类名 - 对 SSR 场景，服务端需输出初始主题对应的一份内联
<style>（带data-theme="light"标记），避免白屏闪动
CSS 自定义属性（CSS Variables）如何与 JS 主题状态同步
仅靠 :root 里一堆 --color-bg: #fff 不足以支撑多主题——变量值必须随主题实时更新，且不能依赖 JS 反复 setProperty，否则性能差、难维护。
- 每个主题对应一个独立的
:root[data-theme="dark"]块，把所有变量声明集中写在里面，JS 只负责切换document.documentElement.dataset.theme - 避免在 JS 中手动遍历设置几十个
setProperty，那会丢失 CSS 层级继承和计算逻辑 - 深色/浅色自动适配场景下，可用
@media (prefers-color-scheme: dark)作为 fallback，但不可替代 JS 主动控制，因用户可能覆盖系统偏好 - 变量命名保持语义化，如
--surface-level-1而非--bg-1，便于主题扩展时理解层级关系
切换主题时如何避免布局抖动和重绘失控
常见错误是主题 class 加在 <body> 上，结果导致所有子元素重排重绘；或 CSS 中大量使用 background: var(--color-bg) 却没设默认值，导致切换瞬间回退到浏览器默认背景色。
- 主题 class 必须加在
document.documentElement（即<html>标签），确保 CSS 变量作用域稳定，且不影响 document 流 - 所有用到变量的地方，必须提供降级值：
color: var(--text-primary, #333)，防止变量未定义时样式崩溃 - 动画过渡要限制在颜色、opacity 等合成层属性上，避免触发布局（layout）或绘制（paint），例如用
transition: background-color 0.2s ease而非transition: all - 图片、SVG 图标等资源若也需主题适配，不要用 CSS
filter: invert()模拟暗色，而应通过data-theme属性配合background-image: url(...)切换实际资源路径
:root {
--text-primary: #1a1a1a;
--surface-bg: #ffffff;
}
:root[data-theme="dark"] {
--text-primary: #e0e0e0;
--surface-bg: #121212;
}
body {
color: var(--text-primary, #1a1a1a);
background-color: var(--surface-bg, #ffffff);
transition: background-color 0.2s ease, color 0.2s ease;
}
主题切换本身不复杂，真正容易出问题的是变量作用域错位、降级值缺失、以及把「切换」当成纯视觉操作而忽略资源加载时机。尤其当主题涉及字体、阴影、间距等非颜色类变量时，CSS 声明结构必须足够扁平可预测，否则调试成本会指数上升。 
