根本原因是 darkMode 配置缺失或错误：v3 默认不启用 dark: 变体，必须在 tailwind.config.js 顶层显式声明 darkMode: 'class' 或 'media'，且需配合 HTML 根节点类名或媒体查询使用。
升级 Tailwind CSS v3 后深色模式失效，根本原因不是版本兼容问题，而是 darkMode 配置被隐式移除或写错位置——v3 默认不再启用 dark: 变体，不显式声明就等于关掉整个暗色逻辑。
tailwind.config.js 里漏了 darkMode 字段
v2 中 darkMode 默认为 false，v3 起改为“不声明即不生成任何 dark: 类”。哪怕你写了 dark:bg-gray-800，只要配置里没这行：
darkMode: 'class'
编译结果里就压根没有这条 CSS 规则。常见误操作包括：
- 把
darkMode: 'class'塞进theme.extend或plugins里（必须是module.exports顶层字段） - 写成
darkMode: true、darkMode: 'dark'或空字符串（只接受'class'和'media'） - TypeScript 配置中类型未导出完整，导致配置未被读取
用了 class 策略但没操作 document.documentElement
darkMode: 'class' 生效的前提，是 元素上有 dark 类。Tailwind 只检查 document.documentElement，不看 body 或任意容器。
立即学习“前端免费学习笔记（深入）”；
常见错误：
- 在组件里给
<div class="dark"> 加类——无效，<code>dark:不继承 - 用
document.body.classList.toggle('dark')切换——SSR 框架（如 Next.js）会触发 hydration mismatch - 初始化脚本放在
底部或DOMContentLoaded里——用户先看到一帧亮色，再闪到暗色（“闪白”）
正确做法：内联执行、早于 CSS 加载、包 try/catch，例如：
(() => {
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 {}
})()
用了 media 策略但样式没生效
darkMode: 'media' 下，dark: 类只在 @media (prefers-color-scheme: dark) 内生效，完全绕过 JS 和 DOM 类名。失效通常不是配置问题，而是使用习惯导致的漏项：
- 只写了
dark:bg-gray-800，但没配基础色（如bg-white），导致深色下背景透明或不可见 - CSS 变量（如
color: var(--text-color)）没做系统适配，仍取浅色值 - 第三方组件库内部样式没走 Tailwind 的
dark:逻辑，需手动覆盖 - 本地开发服务器缓存旧 CSS，改完配置后没重启构建进程
dark: 变体写对了但颜色还是不对
Tailwind 不会为 text-gray-700 自动推导深色版本。所有需适配的样式都得显式加前缀：
- 错：
text-gray-700→ 深色下仍是灰得看不清 - 对：
text-gray-900 dark:text-gray-100 - 组合变体建议
dark:hover:bg-gray-700（先限定深色，再限定悬停），可读性更好
最容易被忽略的是：配完 darkMode: 'class' 只是开了门，真正让暗色可用，得每一处颜色、边框、阴影都补上 dark: ——这不是可选项，是强制要求。
