dark:变体不生效是因为tailwind只检测元素是否含dark类，而非自动响应系统偏好；必须手动添加dark类并用document.documentelement.classlist动态控制，避免加在或子元素上。
dark:变体不生效？先检查有没有dark类
Tailwind 的 dark: 变体只在 元素上存在 dark 类时才触发，不是靠系统偏好自动生效，也不是看 或某个容器。常见错误是把 dark 加到 上，结果 dark:bg-gray-900 完全没反应——因为 Tailwind 根本没找到作用域。
验证方法：打开 DevTools，选中 元素，确认 class 列表里有 dark；没有就手动加进去测试：。能生效再撤掉，换成 JS 动态控制。
-
document.documentElement.classList.toggle('dark', isDark)是唯一可靠写法，document.body.classList.toggle('dark')在 Next.js/Nuxt 等 SSR 框架里会引发 hydration mismatch - SSR 渲染时无法读 localStorage，所以服务端需 fallback 到系统偏好（靠初始 HTML 注入），客户端再用 JS 修正
- 别在组件里写
dark:bg-gray-800还指望父级“传”主题——它不继承，只看最近的、带dark的祖先（通常是）
页面加载闪白（FOUC）怎么避免
“先亮后暗”是因为浏览器渲染 HTML/CSS 早于 JS 执行， 默认没 dark 类，等 JS 跑完才加上——中间这段空白就是闪白。
解决办法只有一个：把初始化逻辑写成内联 <script></script>，放在 里、所有 <link rel="stylesheet"> 之前。不能用 DOMContentLoaded，不能塞进 React useEffect，都太晚。
- 先读 localStorage，没值再查
window.matchMedia('(prefers-color-scheme: dark)')，立刻设置document.documentElement.classList - 必须同步调用
localStorage.setItem('theme', 'dark')，否则刷新就回退到系统偏好 - 监听系统变化要用
mediaQuery.addEventListener('change', ...)，Safari 14+ 支持，旧版极少需轮询
用户手动切换后如何保持状态优先级
用户点了一次“切深色”，下次访问就应该默认深色，而不是又读系统偏好——这是基本体验。但优先级顺序必须明确：用户手动选择 > 系统偏好 > 默认亮色。
关键不在“存 localStorage”，而在“读取时的判断逻辑”。不能只靠 localStorage.getItem('theme') === 'dark' 就设 dark，得结合是否存在用户主动设置的痕迹。
- 初始化时：如果
localStorage.theme存在，直接用它；不存在，才用window.matchMedia初始化 - 按钮点击事件里，必须同时执行两件事：
document.documentElement.classList.toggle('dark')和localStorage.setItem('theme', isDark ? 'dark' : 'light') - 不要用
!localStorage.theme && isSystemDark这种逻辑覆盖用户选择——那等于无视用户意图 - SSR 场景下，服务端没法读 localStorage，所以得靠初始 HTML 注入一个
data-theme属性或内联 script，告诉客户端“这次该按什么来”
class 冲突和样式覆盖容易踩的坑
dark:bg-gray-900 和 bg-white 写在同一元素上，谁赢不是靠“先后”，而是 CSS 特异性：Tailwind 编译后生成的是 .dark .dark\:bg-gray-900，而 bg-white 是 .bg-white。前者需要 才激活，后者无条件生效。
最稳妥写法是显式配对：bg-white dark:bg-gray-900，而不是混用 dark:bg-gray-900 bg-white —— 后者中 bg-white 会始终覆盖暗色下的背景色。
- 避免在同一个 class 字符串里同时写
dark:bg-和bg-，行为难预测，调试时容易绕晕 - 别给工具类加
!important，它会破坏dark:的条件性，导致暗色模式彻底失效 - 自定义颜色时，确保
tailwind.config.js里darkMode: 'class'已正确配置（这是前提，但不是万能开关）
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
