最稳方式是用:root定义变量+data-theme属性切换+CSS层级覆盖；因data-theme语义清晰、无class冲突、支持TS类型约束，而setProperty仅适合单变量微调，不适用于整套主题切换。
直接结论：用 :root 定义变量 + document.documentElement.setAttribute 切换 data-theme + CSS 层级覆盖，是最稳、最易维护、兼容性最好的方式。不推荐直接操作 style.setProperty 批量写入，也不建议靠切换多个 <link> 标签。
为什么选 data-theme 而不是 class 切换主题？
两者都能工作，但 data-theme 更语义清晰、无样式污染风险、且便于 TypeScript 类型约束（比如 type Theme = 'light' | 'dark' | 'neo'）。class 方式容易和业务 class 冲突（比如你写了 .dark 但组件库里也有 .dark），而 data-theme="dark" 是专属控制层。
实际 CSS 写法差异很小：
:root {
--bg: #fff;
--text: #333;
}
:root[data-theme="dark"] {
--bg: #121212;
--text: #e0e0e0;
}
关键点在于：所有主题变量必须写在 :root 下，再用属性选择器做覆盖，否则局部作用域会丢失继承链。
立即学习“前端免费学习笔记（深入）”；
document.documentElement.style.setProperty 为什么慎用？
它适合单个变量微调（比如动态按钮色、实时滑块反馈），但不适合整套主题切换——因为你要手动同步几十个变量，漏一个就会样式错乱，且无法利用 CSS 层叠优先级做 fallback。
常见踩坑点：
- 没清空旧变量：多次调用
setProperty不会自动删除已设值，旧值残留导致冲突 - 没处理 localStorage 同步：页面刷新后变量全丢，得额外写初始化逻辑
- 无法支持 CSS 动画过渡：
var(--bg)值变了，但 background-color 没声明transition就不会动 - SSR 不友好：服务端渲染时
document不存在，直接报错
真正该用它的场景是：用户拖拽调整主色调，实时预览效果——而不是“切换主题”这个离散动作。
如何让主题切换真正响应式？
响应式不只是适配屏幕尺寸，更是对系统偏好、用户操作、持久化状态的联动响应。核心是三层同步：
-
DOM 层：用
document.documentElement.setAttribute('data-theme', theme)触发 CSS 重计算 -
存储层：写入
localStorage.setItem('theme', theme)，并在onMounted或DOMContentLoaded时读取 -
系统层：监听
prefers-color-scheme，用window.matchMedia('(prefers-color-scheme: dark)')做兜底（比如用户没手动选，就按系统来）
注意：不要在监听回调里直接改 data-theme——要先判断当前值是否已匹配，避免无限循环触发。
主题变量命名与组织的实际约束
别用 --primary 这种模糊名，容易在多主题下歧义。推荐分层命名：
-
--color-bg-default（背景主色） -
--color-text-on-bg（文字在背景上的对比色） -
--color-border-interactive（可交互边框色）
这样即使加了 neo 主题，也能明确知道 --color-bg-default 是什么角色，而不是猜 --primary 在深色下是不是还该是蓝色。
另外，所有变量必须定义在 :root，哪怕某个主题只用到其中 30%——否则子组件用 var(--xxx) 时，若父级没定义，就会回退到浏览器默认值或 var(--xxx, #000) 的 fallback，结果不可控。
