用CSS自定义属性统一管理主题变量，集中定义、语义命名、作用域隔离、提供fallback，并通过JS对象化批量注入实现可维护的主题切换。
多主题维护难，本质是颜色、间距、圆角这些值散落在各处。用 CSS 自定义属性（--color-primary、--spacing-md）统一收口，就能把“改主题”变成“改一组变量值”，而不是满项目搜 #3498db。
为什么直接替换 class 或 <link> 标签会出问题
看似快，但实际容易触发样式闪烁、伪类失效、媒体查询被忽略。根本原因是：整套 CSS 规则被重新加载或重排，浏览器需要重计算、重绘，且 :hover、::before 等依赖上下文的规则可能因作用域断裂而丢失。
更隐蔽的问题是：如果你在 JS 里拼接 <style> 注入，会违反 CSP 策略；如果用 !important 覆盖变量值，后续 JS 调用 setProperty() 就完全失效——DevTools 里都看不到变量被修改的痕迹。
- 不要用
document.body.className = 'theme-dark'配合一堆.theme-dark .btn { background: #1a202c }写法 - 避免在多个 CSS 文件里重复定义
:root，构建时可能覆盖或冲突 - 别在
var(--x)里嵌套计算再套var(--y)，部分旧版 Safari 对嵌套var()支持不稳
怎么组织 :root 变量才不乱
所有主题相关值必须集中在一个可维护的源头，不是堆在 :root 里就完事。命名要有业务含义，比如 --color-surface 比 --bg-1 强十倍；基础设计 token（颜色、字号、圆角）放全局，组件专属变量（如 --card-padding）应限制在组件作用域内，用 .card { --card-padding: 16px; } 定义。
立即学习“前端免费学习笔记（深入）”；
- 全局变量加语义前缀：
--color-primary、--spacing-sm、--radius-lg - 禁止裸名：
--red、--c1这类命名上线后根本没法 grep 或交接 - 每个变量都要有 fallback：
color: var(--color-text, #333);，防未定义导致样式崩塌 - 用 Chrome DevTools 的 Styles 面板点击变量名旁的小箭头，能直接跳转到定义位置——比全局搜索
--color-快得多
JS 动态切换主题时 setProperty 不生效？先查这三处
调用 document.documentElement.style.setProperty('--color-bg', '#1a202c') 后没变化，大概率不是 JS 写错了，而是 CSS 层级或继承链断了。
- 检查是否用了
!important在 CSS 里硬写死值，它会切断变量链 - 确认目标元素的父级 DOM 节点确实声明了该变量（CSS 变量靠继承，不是全局广播）
- 留意
@media (prefers-color-scheme: dark)是否和data-theme冲突——data-theme="light"时，媒体查询里的:root规则不该生效，否则优先级错乱 - 首次加载时，先读
localStorage.getItem('ui-theme')，再 fallback 到matchMedia('(prefers-color-scheme: dark)')，避免白屏闪动
主题配置对象化 + 批量注入才是可持续方案
把每个主题写成一个 plain object，比分散在多个 :root[data-theme="xxx"] 块里更利于 CI 检查、i18n 对齐、甚至生成设计 Token 文档。
例如：
const themes = {
light: {
'--color-surface': '#ffffff',
'--color-text': '#1a202c',
'--border-radius': '4px'
},
dark: {
'--color-surface': '#1a202c',
'--color-text': '#e2e8f0',
'--border-radius': '6px'
}
};
切换时只需：
Object.entries(themes.dark).forEach(([prop, val]) => {
document.documentElement.style.setProperty(prop, val);
});
这样做的好处是：增删主题不用改 CSS，只改 JS 对象；变量名一致性由代码校验；配合 TypeScript 还能做 key 的枚举约束。真正难的不是写切换逻辑，而是确保所有组件样式都只通过 var(--xxx) 引用变量——这点漏一个，整个主题系统就出现“局部失联”。
