darkMode 必须显式配置在 tailwind.config.js 顶层，值为 'class' 或 'media'；class 模式下需操作 document.documentElement 并内联初始化脚本防闪白；所有适配样式须手动加 dark: 前缀。
darkMode 必须显式写在 tailwind.config.js 顶层
不写 darkMode 字段，或写错位置、值，dark: 类就根本不会出现在最终 CSS 里——不是失效，是编译时被彻底丢弃。常见错误包括：darkMode: true、darkMode: 'dark'、把配置塞进 theme.extend 或 plugins 里。正确写法只有一处：
darkMode: 'class' 或 darkMode: 'media'，且必须放在 module.exports 的顶层对象中。
class 策略下必须操作 document.documentElement
Tailwind 只检查 元素是否含 dark 类。给 加类完全无效，尤其在 Next.js/Nuxt 等 SSR 框架中会引发 hydration mismatch 和首屏闪白。
切换逻辑必须用：
立即学习“前端免费学习笔记（深入）”；
document.documentElement.classList.toggle('dark')- 初始化脚本要内联在
中，不能依赖DOMContentLoaded或外部 JS 文件 - 服务端渲染环境（如 SSR）下
window不存在，必须包try/catch
防“闪白”靠的是执行时机，不是 CSS 写法
浏览器先解析 HTML/CSS，再执行 JS。如果 JS 在 底部或事件监听里才加 dark 类，用户必然看到一帧浅色 → 瞬间变暗的闪烁。
最小可行初始化脚本（直接贴进 ）：
(() => {
try {
const stored = localStorage.getItem('theme')
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
const shouldDark = stored === 'dark' || (stored !== 'light' && prefersDark)
document.documentElement.classList.toggle('dark', shouldDark)
} catch {}
})()
这段代码必须早于任何 CSS 加载，且不能抽离为外部文件。
dark: 不是自动推导，每一处都要手动加前缀
Tailwind 不会为 text-gray-700 自动补一个深色版本。写了 text-gray-700，深色下还是那个灰，可能直接看不见。
所有需适配的样式都得显式声明：
bg-white dark:bg-gray-800text-gray-900 dark:text-gray-100border-gray-200 dark:border-gray-700- 组合变体建议把
dark:放前面，比如dark:hover:bg-gray-700，可读性更好
最容易被忽略的是：配完 darkMode: 'class' 只是开了门，真正让暗色模式可用，得逐个检查文字、边框、focus ring、背景这些地方有没有补上 dark: ——漏一处，那一块在深色下就可能出问题。
