暗色模式加载闪白的根本原因是浏览器先渲染无dark类的HTML，JS执行后才添加类。解决方案是将同步初始化脚本内联于<head>中，立即读取localStorage或系统偏好并设置document.documentElement.classList，同时确保Tailwind配置darkMode: 'class'且切换时同步更新DOM与localStorage。
为什么暗色模式一加载就闪白
根本原因是浏览器先渲染了无 dark 类的 HTML，等 JS 执行完才加类——这个时间差肉眼可见。哪怕只延迟几十毫秒，浅色样式也会“露一下脸”。document.documentElement.classList.toggle('dark') 放在 DOMContentLoaded 或 React 的 useEffect 里，都太晚了。
初始化脚本必须塞进 <head> 且同步执行
不能外链、不能 defer、不能 async，必须内联并立即运行。否则 CSS 已开始解析，dark 类还没加上，样式就按默认走一遍。
- 正确位置：
<head><script>...</script></head> - 逻辑要一步到位：读
localStorage.getItem('theme')→ fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches→ 立即操作document.documentElement.classList - 别包
try/catch外壳以外的任何异步包装，比如setTimeout、Promise.resolve().then()
切换函数必须同时更新 DOM 和 localStorage
只改类名或只存 localStorage，都会导致状态错位。刷新后还原成系统偏好，或多标签页不同步，本质都是这里没对齐。
- 切换时务必两件事一起做：
document.documentElement.classList.toggle('dark')+localStorage.setItem('theme', isDark ? 'dark' : 'light') - 监听
storage事件，让其他标签页也能响应：window.addEventListener('storage', e => { if (e.key === 'theme') { ... } }) - 避免用
document.body.classList—— Tailwind 默认只看document.documentElement，SSR 框架（如 Next.js）会因此 hydration mismatch
tailwind.config.js 里漏配 darkMode: 'class' 就等于没开
不是“失效”，是编译时直接丢弃所有 dark: 类。连警告都没有，CSS 文件里压根找不到 .dark .dark\:bg-gray-800 这种规则。
立即学习“前端免费学习笔记（深入）”；
- 必须是顶层字段：
module.exports = { darkMode: 'class', ... }，不能塞进theme.extend或plugins - 值只能是
'class'或'media'，true、'dark'、'auto'全部非法 - TS 配置要注意类型导出，确保配置被 Tailwind CLI 正确读取，否则和没写一样
最常被忽略的是：初始化脚本里没 fallback 到系统偏好，或者用了 document.body 当操作目标。这两个点只要错一个，闪白就躲不掉。
