darkMode 配置必须设为 'media'，否则 dark: 类不会响应系统深色偏好；设为 'class' 或 false 会禁用媒体查询，字符串格式是唯一合法形式，且需移除所有 JS 类操作以避免 FOUC。
darkMode 配置必须设为 'media'
Tailwind 默认不自动响应系统深色偏好，除非你显式设置 darkMode: 'media'。v3 起虽会 fallback 到 media 策略，但行为不稳定，尤其在 SSR 或构建工具差异下容易失效。不写这行配置，dark: 类就只认 dark 类名，不会监听 prefers-color-scheme。
正确写法：
module.exports = {
darkMode: 'media',
theme: {
extend: {},
},
plugins: [],
}
-
darkMode: 'class'和darkMode: 'media'互斥——选了 class 就彻底无视系统偏好 - 设成
false会让所有dark:变体直接被忽略，样式不生成 - 不要写成
darkMode: ['media']或darkMode: "media"以外的格式，字符串值是唯一合法形式
不需要 JS 控制，但得确保 HTML 渲染时没手动加 dark 类
media 模式下，Tailwind 完全依赖浏览器媒体查询，不是靠 JS 添加类触发。如果你在 <html> 上写了 class="dark" 或用 JS 初始化加了 dark，反而会覆盖系统判断，导致“本该亮却变暗”或“本该暗却不变”。
常见错误场景：
立即学习“前端免费学习笔记（深入）”；
- 服务端渲染（如 Next.js）中，
document.documentElement.classList.add('dark')在 SSR 阶段执行 → 服务端没window，报错或静默失败 - 客户端 JS 一上来就
classList.toggle('dark')→ 强行覆盖系统状态，用户根本切不动 - 本地开发时开了深色系统，但测试机是亮色，忘了清 localStorage 导致残留
theme=dark干扰 media 行为
dark: 样式生效的前提是媒体查询匹配
dark:bg-gray-800 这类规则，编译后实际生成的是：
@media (prefers-color-scheme: dark) {
.dark\:bg-gray-800 {
--tw-bg-opacity: 1;
background-color: rgb(30 41 59 / var(--tw-bg-opacity));
}
}
也就是说，它不依赖任何 DOM 类，只看当前系统是否满足 prefers-color-scheme: dark。验证方式很简单：
- Chrome DevTools → Rendering 面板 → Emulate CSS media feature →
prefers-color-scheme切换为dark或light - macOS 系统设置 → 外观 → 切换深色/浅色，页面应实时响应
- 注意：iOS Safari 对
prefers-color-scheme支持从 iOS 13.4 起才稳定，旧版本会 fallback 到 light
避免 FOUC（闪屏）的关键是移除 JS 初始化逻辑
media 模式天然无 JS 依赖，但很多人习惯性保留切换按钮、localStorage 读写、useEffect 等代码——这些对纯 media 场景不仅多余，还会引发首次加载闪白再变暗的问题。
如果你只想要系统自动切换，就该：
- 删掉所有操作
document.documentElement.classList的 JS - 删掉
localStorage.getItem('theme')相关逻辑 - 删掉
window.matchMedia监听和同步代码 - 按钮组件如果还存在，确保它只在
darkMode: 'class'下启用，否则点击会破坏 media 行为
真正需要手动控制时，再切回 class 模式——media 和 class 不能混用，这是最常被忽略的边界。
