必须通过 document.documentElement.style.setProperty 设置 css 自定义属性，主题配置应预存为对象并批量注入，切换后同步更新 data-theme 属性和 localStorage，注意兼容性与性能优化。
主题切换必须用 document.documentElement 设置 CSS 变量
直接改 style 属性或操作 标签加载不同 CSS 文件，无法实现真正的“动态变量更新”。CSS 自定义属性（--color-bg 等）的作用域在 :root（即 document.documentElement），只有在这里设置，才能让整个页面响应式重绘。
常见错误是写成 document.body.style.setProperty(...)，这只会作用于 元素本身，子元素继承不到，或者继承但未触发重排重绘。
- ✅ 正确做法：统一通过
document.documentElement.style.setProperty('--color-bg', '#222') - ❌ 错误做法：改
document.querySelector('.theme-switcher').style或操作内联style属性 - ⚠️ 注意：多次调用
setProperty不会覆盖旧值，而是叠加；清空某变量需设为''（空字符串）或重新赋默认值
主题数据应预存为 js 对象，而非硬编码在切换逻辑里
把深色/浅色主题的全部变量值写死在 if/else 里，后期维护痛苦、易出错、无法扩展。推荐用对象结构组织主题配置，再用一个函数批量注入。
例如：
立即学习“Java免费学习笔记（深入）”；
const themes = { light: { '--color-bg': '#fff', '--color-text': '#333', '--color-border': '#eee' }, dark: { '--color-bg': '#1a1a1a', '--color-text': '#f0f0f0', '--color-border': '#333' } }; function applyTheme(themeKey) { const theme = themes[themeKey]; if (!theme) return; Object.entries(theme).forEach(([prop, value]) => { document.documentElement.style.setProperty(prop, value); }); }- 主题对象键名必须与 CSS 中使用的变量名完全一致（含
--前缀） - 避免在对象里写
var(--color-bg)这类引用，CSS 变量不支持 JS 对象内嵌套解析 - 如需支持用户自定义主题，可将
themes改为从 localStorage 读取并合并默认值
切换后需同步更新 data-theme 属性和 localStorage
仅改 CSS 变量不够。用户刷新页面后状态丢失，且某些组件（比如依赖 [data-theme="dark"] 的 CSS 选择器）需要 dom 属性配合才能生效。
- ✅ 必须执行：
document.documentElement.setAttribute('data-theme', 'dark') - ✅ 必须保存：
localStorage.setItem('ui-theme', 'dark') - ✅ 初始化时要读取：
const saved = localStorage.getItem('ui-theme') || 'light'，再调用applyTheme(saved) - ⚠️ 注意：不要监听
localStorage变化来触发主题更新——它只在其他 tab 触发，当前页需主动读取
兼容性与性能：IE 不支持，大量变量需防 layout thrashing
CSS 自定义属性在 IE 中完全不可用，如果项目还需兼容 IE，这套方案必须降级为 class 切换 + 多份 CSS 规则（如 .theme-dark .card { background: #111; }）。
对于含 20+ 变量的主题，连续调用 setProperty 可能引发强制同步布局（layout thrashing），尤其在低端设备上卡顿。
- ✅ 推荐合并：用
Object.assign(document.documentElement.style, theme)替代循环setProperty（注意：此法仅适用于无连字符的属性名，CSS 变量仍需用setProperty） - ✅ 更稳妥：用
requestAnimationFrame批量更新，或先拼接style字符串再一次性 setAttribute - ❌ 不要用
getComputedStyle在每次切换前读取旧值——完全没必要，也不影响新值生效
主题切换的核心不在“怎么换”，而在“换完之后所有依赖它的样式是否真的重绘了”。很多 bug 出现在变量设了、DOM 属性也改了，但某个按钮背景还是白的——大概率是 CSS 选择器权重没压过旧规则，或者变量名拼错了一个字符。