怎样用Tailwind CSS优雅实现后台暗黑模式切换-css教程-PHP中文网

必须配置 darkMode: 'class' 并操作 document.documentElement，配合内联初始化脚本，否则暗色模式不生效、刷新丢失、SSR 水合错乱；漏配或误配 darkMode 会导致 dark: 类被完全剔除。

怎样用tailwind css优雅实现后台暗黑模式切换

必须用 darkMode: 'class' 配置 + 操作 document.documentElement + 内联初始化脚本，否则暗色样式不生效、刷新丢失、SSR 下水合错乱。

tailwind.config.js 里漏写 darkMode 就等于没开暗黑模式

Tailwind v3+ 默认不启用 dark: 变体。哪怕你写了 dark:bg-gray-800，只要配置里没这行：

darkMode: 'class'

编译器就直接剔除所有 dark: 类——不是失效，是压根没生成，连警告都没有。

非法值如 darkMode: true、darkMode: 'dark'、darkMode: '' 全部等同于未配置
darkMode 必须是顶层字段，不能塞进 theme.extend 或 plugins
用 TypeScript 写配置时，确保导出类型正确（比如 defineConfig），否则 Vite/Next.js 可能读不到

切换必须操作 document.documentElement，不是 body

dark: 变体只检查元素上是否有 dark 类。改 document.body.classList 是常见错误，尤其在 Next.js/Nuxt 等 SSR 框架中会导致首屏闪白、hydration mismatch 甚至报错。

正确写法：document.documentElement.classList.toggle('dark')
错误写法：document.body.classList.toggle('dark')（即使视觉暂时正常，SSR 场景下必然出问题）
别在组件内给局部容器加 dark 类“期望主题透传”——dark: 不继承，只看最近带 dark 的祖先（通常是 html）

防闪白的关键：内联脚本要在 CSS 加载前执行

浏览器先渲染无 dark 类的浅色样式，JS 后加载再加类，就会“闪白”。解决办法只有一个：把初始化逻辑写成立即执行函数，放在内的 <script></script> 标签里，且不能包 DOMContentLoaded 或 window.onload。

Tailwind CSS 3.4.19

Tailwind CSS 3.4.19 是 v3 长期维护分支版本，适合仍使用 v3 配置和构建流程的项目。此页提供 npm 官方包。

下载

最小可行内联脚本（可直接贴进 HTML 的）：

(() => {
  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 {}
})()