必须在html元素加dark类并配置darkMode:'class'，否则dark:样式不生效；切换需操作document.documentElement、同步localStorage，并用内联脚本防闪屏。
直接给 html 元素加 dark 类，再配 darkMode: 'class'，否则 dark:bg-gray-800 这类样式永远不生效。
tailwind.config.js 必须显式配置 darkMode
不写这行，所有 dark: 类都会被 Tailwind 编译器直接剔除，连警告都没有。
- 只接受两个值：
'media'（纯系统偏好）或'class'（手动控制），别写true、'dark'或空字符串 -
darkMode: 'class'是唯一能支持按钮切换 + 记住用户选择的方案；'media'无法手动干预，刷新后也不保留状态 - 确保
content字段包含所有用到dark:的模板路径，否则 JIT 模式下类名可能漏生成
切换逻辑必须操作 document.documentElement
把 dark 类加在 <body> 或组件 div 上是无效的——Tailwind 只检查 <html> 元素上的 dark 类。
- 正确写法：
document.documentElement.classList.toggle('dark') - 错误写法：
document.body.classList.toggle('dark')（SSR 场景下会导致水合错乱） - 切换时要同步写入
localStorage.setItem('theme', 'dark')，否则刷新就回浅色 - 初始化时从
localStorage.getItem('theme')读取，没值则 fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches
防闪屏的关键：内联脚本要在 CSS 加载前执行
页面先渲染浅色样式，JS 再加 dark 类，就会出现“闪白”——尤其在慢网或 SSR 场景下非常明显。
立即学习“前端免费学习笔记（深入）”；
- 把初始化逻辑写成 IIFE，放在
<head>里的<script>标签中（不是外部 JS 文件） - 必须包一层
try/catch，因为服务端渲染时window不存在 - 示例内联脚本：
(() => { try { const saved = localStorage.getItem('theme'); const prefersDark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches; const shouldDark = saved === 'dark' || (saved !== 'light' && prefersDark); document.documentElement.classList.toggle('dark', shouldDark); } catch {} })();
最易被忽略的是：深色模式不是加个 dark 类就完事，而是整套颜色体系要重定义——比如 text-gray-700 在暗色下可能还是灰得看不清，得换成 dark:text-gray-300 才真正可用。
