最常见原因是变量未在:root中声明，导致var()回退到transparent或继承值；CSS变量仅通过DOM继承链传递，:root是唯一全局可访问位置；JS切换主题应使用document.documentElement.style.setProperty()并确保DOM就绪。
为什么 setProperty 后颜色没变
最常见原因是变量根本没在 :root 里声明。浏览器遇到未定义的 var(--bg-primary) 不会报错，而是直接 fallback 到继承值或 transparent——不是“没变”，是“失效了”。
另一个高发场景：你在 .theme-dark 类里声明变量，却试图从 body 或组件内读取。CSS 变量不自动跨选择器继承，只靠 DOM 继承链传递，:root 是唯一能保证全局可访问的位置。
-
:root必须显式声明所有主题变量，哪怕浅色模式下值相同也要写全，例如：:root { --bg-primary: #fff; --text-primary: #222; } - 深色覆盖必须用
[data-theme="dark"] :root，别用.dark :root——前者权重稳定（110），后者容易被业务 class 覆盖 - 每个
var()都得带回退值，比如color: var(--text-primary, #222);，否则变量未定义时文字可能彻底消失
如何用 JavaScript 安全切换主题
核心就一句：document.documentElement.style.setProperty()。别用 cssText 覆盖，那会清空所有已有内联样式；也别动态插入 <style> 标签，太重。
JS 执行时机比写法更重要：必须等 DOM 就绪，否则 document.documentElement 还没准备好。用 DOMContentLoaded 比 window.onload 更稳妥。
立即学习“前端免费学习笔记（深入）”；
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
- 批量修改建议封装函数，避免重复写
document.documentElement.style：function setTheme(vars) { Object.entries(vars).forEach(([k, v]) => document.documentElement.style.setProperty(k, v) ); } - 切换前先读一次 localStorage，有值就立刻设
document.documentElement.dataset.theme，放在<head>内联 script 里，防 FOUC - 切完主题后记得同步写入 localStorage：
localStorage.setItem('ui-theme', 'dark')，否则刷新就回退
data-theme 和 prefers-color-scheme 怎么共存
@media (prefers-color-scheme: dark) 是纯 CSS 行为，加载即生效；data-theme 是 JS 主动控制的状态。两者不冲突，但优先级必须明确：用户手动选择 > 系统偏好。
初始化逻辑要分三步走：先查 localStorage，有值就用；没值再查 matchMedia('(prefers-color-scheme: dark)').matches 做 fallback；最后监听系统变化，但仅当用户没手动切过主题时才响应。
- 默认只在
:root定义浅色变量，@media里只重设变量值，不写完整样式块 -
[data-theme="dark"] :root和@media (prefers-color-scheme: dark)可并存，但前者权重更高，能压过后者 - 不要在
@media里写.button { color: #eee; }这类具体样式，只改--text-primary等变量，保持逻辑集中
切换时页面闪白或文字消失
这是变量回退值缺失 + JS 执行延迟导致的典型 FOUC（Flash of Unstyled Content）。浏览器先按未定义变量渲染，JS 后改，中间出现空白期。
真正难的不是“怎么切”，而是让切换过程不可见。关键不在 JS 多快，而在 HTML 加载初期就预埋状态。
- 在
<head>放内联 script：<script>document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';</script> - 所有
var()都必须带回退值，尤其背景和文字色：background: var(--bg-base, #fff); color: var(--text-primary, #222); - 避免连写十次
setProperty()，改用cssText或封装函数一次注入，减少重排次数
