常见错误是仅设置data-theme属性却未触发css变量重计算，因css自定义属性静态求值、不响应属性变化；必须同步设置data-theme="dark"并调用框架更新方法（如bootstrap的update()），否则:root变量值仍为浅色。
为什么只改 data-theme 属性页面没反应
常见错误是仅设置 document.documentElement.setAttribute('data-theme', 'dark')，却没触发 CSS 变量重计算。CSS 自定义属性不会自动响应属性变化——它只在声明时求值，后续修改需靠浏览器重新匹配样式规则并应用新变量值。而多数框架（如 Bootstrap 5.3+）的深色模式依赖两层：属性选择器 + 变量值，但变量值本身不随属性动态刷新。
必须同步做两件事：
- 设置
data-theme="dark"到html元素 - 显式调用框架提供的更新方法，比如 Bootstrap 的
bootstrap.Theme.getOrCreateInstance().update()
漏掉第二步，:root 下的 --bs-body-bg 等变量值仍为浅色，所有组件背景、文字颜色都不会变。检查方式：打开开发者工具 → 查看 :root 节点 → 切换后变量值是否更新。
@media (prefers-color-scheme: dark) 必须放在 :root 默认定义之后
媒体查询本身不提升优先级，只靠声明顺序覆盖。如果深色规则写在浅色规则之前，或被包裹在其他媒体查询里（如 @media (max-width: 768px) { @media (prefers-color-scheme: dark) { ... } }），旧版 Safari 会直接忽略。
正确结构必须是：
:root {
--bg-primary: #ffffff;
--text-primary: #1a1a1a;
}
@media (prefers-color-scheme: dark) {
:root {
--bg-primary: #121212;
--text-primary: #e0e0e0;
}
}
注意两点：
- 所有变量必须在
:root中先声明默认值，否则系统设为no-preference或不支持时，var(--bg-primary)会回退到浏览器默认（比如白底黑字） - 不能只覆盖部分变量：漏定义
--border，而组件用了border: 1px solid var(--border, #ccc)，深色下就会显示亮灰边框，对比失常
手动切换和系统偏好如何共存不打架
用户主动点“深色模式”按钮，和系统设为浅色时，两者必须分层处理，不能互相覆盖。强行用 JS 直接改 :root 里的变量值（如 document.documentElement.style.setProperty('--bg-primary', '#121212')），会屏蔽 prefers-color-scheme 的自动响应——下次用户切系统主题，页面毫无反应。
推荐做法是用状态分离：
- 系统偏好兜底：用
@media (prefers-color-scheme: dark)设置初始值，但加:root:not([data-theme])限定，避免干扰手动设置 - 用户选择主导：用
html[data-theme="dark"]块完整覆盖同一组变量，且该块必须写在媒体查询之后 - 初始化时读
localStorage.getItem('theme')，有值就设data-theme；无值则 fallback 到matchMedia('(prefers-color-scheme: dark)').matches
监听系统变化时，只更新 localStorage，不改 data-theme——防止覆盖用户当前选择。
图片、表单、滚动条这些“隐形元素”怎么一起切
CSS 变量对 input、select、textarea、scrollbar、svg fill 等原生控件无效。它们不读取 var(--text-primary)，也不自动响应主题切换。
必须额外声明：
- 在
:root或html上加color-scheme: light dark，通知浏览器“我支持双主题”，让原生控件按系统逻辑适配（Chrome 85+ / Firefox 96+ / Safari 13.3+） - 显式重置表单样式：
input, select, textarea { background: var(--bg-surface); color: var(--text-primary); } - 滚动条需单独写：
html[data-theme="dark"]::-webkit-scrollbar-thumb { background: var(--border); } - SVG 图标若用内联
fill，得改成fill: var(--icon-primary)；用<use></use>引用的，需确保 symbol 定义中也用了变量
最容易被忽略的是 color-scheme 声明——没它，深色系统下 input 边框可能还是亮灰，滚动条 thumb 是浅色，用户第一眼就觉得“没切干净”。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
