Tailwind 的 dark: 变体不生效，主因是 darkMode 配置错误（必须为顶层 'class' 或 'media'）、dark 类未加在 html 元素上、初始化脚本执行过晚、主题状态未同步 localStorage，且需手动编写 dark: 对应样式。
dark: 类不生效，不是 CSS 写错了，而是 Tailwind 根本没生成对应规则，或者生成了但没匹配到作用域——两种情况都指向配置或 DOM 操作的硬性错误。
tailwind.config.js 里 darkMode 没配对
darkMode 必须是顶层字段，且只接受 'class' 或 'media'。其他写法一律无效：
-
darkMode: true、darkMode: 'dark'、darkMode: ''—— 编译时直接忽略，dark:bg-gray-900连 CSS 规则都不会输出 -
darkMode: 'class'写在theme.extend或plugins里 —— 配置未被识别，等同于没写 - TypeScript 项目中类型导出不全（比如漏了
@types/tailwindcss），导致整个 config 文件加载失败
正确写法必须是：
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ["./src/**/*.{js,ts,jsx,tsx}"],
darkMode: 'class', // ✅ 顶格，无缩进，无引号包裹变量
theme: { extend: {} },
plugins: [],
}dark 类没加在 document.documentElement 上
Tailwind 只检查 <html> 元素是否有 dark 类。加在 <body> 或任意子元素上，dark: 变体完全不触发。
立即学习“前端免费学习笔记（深入）”；
-
document.body.classList.toggle('dark')看似合理，实际无效；SSR 框架（如 Next.js）还会报 hydration mismatch - 手动测试时可先硬编码
<html class="dark">，确认样式是否立刻生效 - 若用了自定义
darkSelector（如theme: { darkSelector: 'my-dark-mode' }），JS 里就得用document.documentElement.classList.toggle('my-dark-mode')，不能硬写dark
初始化脚本太晚执行，导致闪白和状态错乱
CSS 渲染早于 JS，如果等 useEffect 或 DOMContentLoaded 才加 dark 类，必然出现“先亮后暗”。
- 必须把判断逻辑写成内联
<script>，放在<head>最顶部、所有<link rel="stylesheet">之前 - 脚本需同步读
localStorage.getItem('theme')，fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches - 必须包裹
try/catch，否则在无window或localStorage的环境（如某些 WebView）会崩溃
最小可用脚本：
(() => {
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 {}
})()切换时没同步 localStorage 和 storage 事件监听
用户点一次“切深色”，刷新就回退，或者多个标签页不同步，本质是状态没闭环。
- 点击按钮时，必须同时做两件事：
document.documentElement.classList.toggle('dark')和localStorage.setItem('theme', isDark ? 'dark' : 'light') - 监听
storage事件，让其他标签页修改主题后，当前页能立刻响应：window.addEventListener('storage', e => { if (e.key === 'theme') { /* 重设 classList */ } }) - 别依赖
sessionStorage做持久化——它关页即丢，无法跨会话保持
最易被忽略的是：darkMode: 'class' 只是开了门，不代表颜色自动适配。你写的 text-gray-700 在深色下很可能还是灰得看不见，必须显式补 dark:text-gray-300。没有自动降级，全靠手写。
