必须在 tailwind.config.js 顶层显式配置 darkMode: 'class'，否则 dark: 类名不会生成；需确保 <html> 元素有 dark 类，初始化脚本须内联于 <head> 并早于 CSS 加载，且所有颜色需手动添加 dark: 变体。
必须在 tailwind.config.js 中显式声明 darkMode: 'class'，否则所有 dark: 类名都不会生成——不是失效，是压根没进最终 CSS 文件。
darkMode 配置必须写在顶层，且值只能是 'class' 或 'media'
常见错误包括：
• 把 darkMode: 'class' 写进 theme.extend 或 plugins 里
• 写成 darkMode: true、darkMode: 'dark' 或空字符串
• 在 TypeScript 配置中类型导出不完整，导致配置未被读取
• 漏掉这个字段（v3+ 不再默认启用，不写就等于关掉）
正确位置示例：
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ["./src/**/*.{js,ts,jsx,tsx}"],
darkMode: 'class', // ✅ 必须是顶层字段
theme: {
extend: {},
},
plugins: [],
}配了 'class' 却没生效？检查 <html> 上有没有 dark 类
Tailwind 只检查 document.documentElement（即 <html> 元素）是否有 dark 类。
• 给 <body> 加 dark 类完全无效，尤其在 Next.js/Nuxt 等 SSR 框架中会引发 hydration error
• 直接在 HTML 模板里写 <html class="dark"> 是最小验证方式
• 动态切换必须用：document.documentElement.classList.toggle('dark')，不是 body
初始化脚本必须内联在 <head>，且早于 CSS 加载
“闪白”不是 bug，是执行时机问题：浏览器先渲染无 dark 类的浅色样式，JS 后加类才触发深色——中间有可见延迟。
解决方式只有一种：
• 脚本不能挂 DOMContentLoaded 或 window.onload
• 必须写成 IIFE，放在 <head> 内联 <script> 中
• 包 try/catch（服务端渲染时 window 不存在）
典型代码：
立即学习“前端免费学习笔记（深入）”；
(() => {
try {
const saved = localStorage.getItem('theme')
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
const shouldDark = saved === 'dark' || (saved !== 'light' && prefersDark)
document.documentElement.classList.toggle('dark', shouldDark)
} catch {}
})()最容易被忽略的是：配完 darkMode: 'class' 只是开了门，真正让暗黑模式可用，还得每处颜色都补上 dark: 变体——比如 text-gray-700 在深色下可能还是灰得看不清，得显式写成 dark:text-gray-300。
