darkmode 必须显式配置为 'class' 或 'media' 且置于 tailwind.config.js 顶层，否则 dark: 类被完全丢弃；需重启构建服务；html 根元素须同步添加 dark 类；所有需适配的样式必须显式加 dark: 前缀；localstorage 持久化与跨标签页同步为体验底线。
darkMode 必须显式配置为 'class' 或 'media'，否则所有 dark: 类在编译时被完全丢弃——不是失效，是压根没生成。
tailwind.config.js 中 darkMode 配置必须写对位置和值
常见错误是把 darkMode: 'class' 塞进 theme 或 plugins 里，或者写成 darkMode: true、darkMode: 'dark'。Tailwind 只接受两个合法值：'class' 和 'media'，且必须放在配置文件顶层。
改完必须重启构建服务（如 npm run dev），Tailwind 不热更配置。
-
darkMode: 'media'→ 完全依赖prefers-color-scheme，无需 JS，也无法手动干预 -
darkMode: 'class'→ 深色模式只在document.documentElement有class="dark"时生效，适合带切换开关的场景 - 不写
darkMode字段，v3+ 默认行为已取消自动启用，等同于关掉深色模式支持
HTML 根元素必须同步拥有 dark 类，且初始化脚本要放对地方
dark:bg-gray-800 不会自己触发样式切换，它只在 存在时才匹配规则 .dark .bg-gray-800。加在 上无效，尤其在 Next.js/Nuxt 等 SSR 框架中会导致 hydration 失败或首屏闪白。
“闪白”不是 CSS 问题，是执行时机问题：浏览器先渲染无 dark 类的浅色样式，JS 后加类才有深色——中间有可见延迟。
- 脚本必须内联在
顶部，不能包在DOMContentLoaded或window.onload里（太晚了） - 必须用
document.documentElement.classList.toggle('dark', shouldDark)，不是body - 需处理三种状态：
'light'（强制亮色）、'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 {}
})()
dark: 变体必须手动加到每一处需要适配的颜色/边框/文字上
Tailwind 不会自动推导深色版本。写了 text-gray-700，深色下还是灰得看不清；写了 border-gray-200，深色下可能变成看不见的浅灰线。所有涉及视觉表现的工具类，只要需要区分主题，就得显式补上 dark: 前缀。
-
bg-white dark:bg-gray-900、text-gray-900 dark:text-gray-100是基础组合 - 图标适配不能靠
dark:invert（Tailwind 不提供该变体），要用 inline SVG +fill="currentColor"+dark:text-white - 与其它变体组合时，
dark:hover:bg-gray-700比hover:dark:bg-gray-700更易读，推荐前者 - SSR 场景下，JS 初始化逻辑需包裹
if (typeof window !== 'undefined')，避免服务端报错
localStorage 持久化不是可选，而是体验底线
用户点一次切换按钮，刷新就回到默认浅色，等于没做。状态不同步还会导致跨标签页不一致：一个页面切了深色，另一个仍是浅色。
切换时必须同步三处：
document.documentElement.classList.toggle('dark')localStorage.setItem('theme', isDark ? 'dark' : 'light')- 监听
storage事件，在其他标签页修改后立即响应
最容易被忽略的是：配了 darkMode: 'class' 只是开了门，真正让深色模式可用，还得每处颜色、边框、阴影、文字都补上 dark: ——漏一处，那一块就在深色下“失明”。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
