用 data-theme 控制主题最稳，因其避免 FOUC、维护简单且不破坏 CSS 变量作用域；切换 link 会触发重下载与重排导致首屏闪白，而 data-theme 仅触发变量重计算，毫秒响应且服务端可直出。
直接用 data-theme 控制主题最稳，别在模板里拼 class 或换 <link href> —— 后者易 FOUC，前者难维护且破坏 CSS 变量作用域。
为什么 data-theme 比切换 <link> 更可靠
切换 <link rel="stylesheet" href="dark.css"> 会触发浏览器重新下载、解析、重排，首屏必闪白；而 data-theme 是纯属性变更，CSS 已加载完毕，变量重计算由浏览器原生优化，毫秒级响应。更关键的是：服务端可直出 ，用户打开即见正确样式，完全规避 FOUC。
- 常见错误：
document.querySelector('link[href*="light"]').remove()+ 动态appendChild新 link —— 网络延迟或 JS 报错时页面彻底无样式 - 兼容性无压力：
data-theme是标准 HTML5 属性，所有现代浏览器（含 Safari 12.1+）都支持 - localStorage 读取后应立即应用，不要等
DOMContentLoaded—— 否则仍可能闪一下默认主题
:root 里定义变量，[data-theme] 里覆盖
CSS 变量必须统一收口在 :root，不同主题靠属性选择器覆盖，而不是写多套独立的 :root 块。否则变量作用域混乱，var(--primary-color) 在深色模式下可能还是浅色值。
- 正确写法：
:root { --bg: #fff; --text: #333; } [data-theme="dark"] { --bg: #1a1a1a; --text: #eee; } - 错误写法：分开写两个
:root，或用.dark :root—— 后者权重低，且无法响应根元素上的data-theme - 变量命名建议用
--theme-bg、--theme-text，避免和业务变量（如--card-padding）混用
模板渲染时只注入 data-theme，子组件禁止设置
模板（如 EJS、Nunjucks、Django）只需在 或 上输出 data-theme="{{ theme }}"。任何子组件、卡片、表格都不该自己加 data-theme —— 这会导致选择器权重冲突，比如 div[data-theme="light"] .btn 会盖过 html[data-theme="dark"] .btn。
立即学习“前端免费学习笔记（深入）”；
- 子组件样式应只消费变量：
background: var(--theme-bg); color: var(--theme-text); - 若需局部反色（如弹窗强制浅色），用 class 控制：
<dialog class="dialog--light"></dialog>，再配.dialog--light { background: var(--theme-bg-light); } - 旧版模板引擎（如 Jinja2 默认过滤 data-*）需显式启用：
environment.policies['json.dumps_kwargs']['ensure_ascii'] = False或改用theme="{{ theme }}"兼容
JavaScript 切换逻辑要防重复、保同步
切换主题不能只改 document.documentElement.setAttribute('data-theme', 'dark') 就完事。得处理 localStorage、系统偏好、按钮状态三者同步，否则用户点两次“深色”却切回浅色。
- 推荐封装为函数：
setTheme(themeValue)，内部统一做：存 localStorage、设属性、更新按钮 UI、触发自定义事件themechange - 监听系统偏好变化：
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', ...)，但仅作 fallback，不覆盖用户手动选择 - 避免多次 addEventListener：用
removeEventListener清旧监听，或用 AbortController（现代写法）
真正容易被忽略的不是怎么切，而是「谁负责读取初始值」——必须在 HTML 解析早期（甚至内联 script 中）就读 localStorage 并设 data-theme，晚于 DOM 构建就来不及了。很多 FOUC 就栽在这一步。
