必须显式配置 darkmode: 'class'，否则 dark: 类在编译时被彻底剔除；正确写法为 module.exports = { darkmode: 'class', content: ['./src/*/.{js,jsx,ts,tsx}'] }，且切换需操作 document.documentelement 并同步 localstorage。
必须显式配置 darkMode: 'class'，否则所有 dark: 类在编译时被彻底剔除——不是 JS 没跑对，而是根本没生成对应 CSS 规则。
tailwind.config.js 的 darkMode 必须写成 'class'
不写 darkMode 字段、写成 true、'dark'、'' 或 'media'，都会导致 dark:bg-gray-800 这类样式完全不生效。Tailwind v3+ 默认倾向 'media'，但“倾向”不等于“启用”，它只影响未声明时的 fallback 行为，而实际编译逻辑仍要求显式声明。
正确写法只有一行：
module.exports = {
darkMode: 'class',
content: ['./src/**/*.{js,jsx,ts,tsx}'],
// 其他配置...
}
-
darkMode: 'media'→ 完全响应系统偏好，document.documentElement.classList.toggle('dark')无效 -
darkMode: 'class'→ 是唯一支持按钮切换 +localStorage持久化的方案 - SSR 框架（如 Next.js）中若漏配，首屏 hydration 会失败，出现样式错乱
切换必须操作 document.documentElement，不能碰 body
Tailwind 默认只检查 元素是否存在 dark 类。加在 或任意组件 <div> 上，<code>dark:bg-gray-800 永远不会匹配。
常见错误写法：document.body.classList.toggle('dark') —— 在 SSR 场景下会导致水合失败，DevTools 里能看到 class 被服务端渲染为浅色，客户端 JS 再加一次深色，触发 DOM diff 错误。
正确操作始终是：
document.documentElement.classList.toggle('dark')
- 切换时同步写入：
localStorage.setItem('theme', shouldDark ? 'dark' : 'light') - 初始化时从
localStorage.getItem('theme')读取，无值则 fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches - 务必包在
try/catch中，避免 SSR 环境报ReferenceError: window is not defined
防闪白：初始化脚本必须内联于
页面先渲染浅色样式，JS 加载后再切深色，中间延迟就是“闪白”。尤其在慢网或 SSR 场景下非常明显。
解决办法是把初始化逻辑写成 IIFE，直接放在 的 <script></script> 标签里（不是外部文件）：
(() => {
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 {}
})()
- 这个脚本必须在任何 CSS 文件加载前执行，否则仍可能闪
- 不要依赖 React useEffect 或 Vue onMounted —— 它们太晚，DOM 已渲染完毕
- 如果用框架（如 Next.js），需用
dangerouslySetInnerHTML注入该内联脚本
dark: 类的顺序和覆盖逻辑容易踩坑
dark: 不是覆盖机制，而是生成带 .dark .dark\:bg-gray-800 的 CSS 规则，最终效果取决于层叠顺序。
错误写法：bg-white dark:bg-gray-900 ✅ 正确；dark:bg-gray-900 bg-white ❌ 后者永远生效。
- 同一元素上混用
bg-white和dark:bg-gray-900时，bg-white必须写在前面 - 避免与自定义 CSS 冲突：比如写了
.card { background: white; }，再加dark:bg-gray-900，很可能被.card的声明覆盖 - 调试技巧：打开 DevTools → Computed → 找 background 属性，看来源是哪条 CSS 规则
最易被忽略的是：加了 dark 类不等于自动适配——你得重定义整套颜色体系，比如 text-gray-700 在深色下依然灰得看不清，必须显式写 dark:text-gray-300 才真正可用。
