Tailwind暗色模式需手动控制html元素的dark类名，dark:仅为样式前缀；darkMode:'class'响应类名，'media'响应系统偏好，二者不可混用；须用localStorage持久化状态并注意SSR水合问题。
dark类名切换需要手动控制元素的class
Tailwind默认不自动管理暗色模式开关，dark: 只是样式前缀，它本身不会触发任何切换逻辑。真正起作用的是你是否在某个祖先元素（通常是 <html>）上加了 dark 类名。如果你只写 dark:bg-gray-800 却没给 <html> 加 dark，那这条样式永远不会生效。
常见错误是直接在组件里用 className="dark:bg-gray-800" 就以为能自动变暗——不行，必须确保父级有 dark 类。
- 推荐在根节点统一控制：
<html className={darkMode ? "dark" : ""}>（React）或通过 JS 动态设置document.documentElement.classList.toggle("dark") - 不要依赖用户系统偏好自动开启：Tailwind 的
darkMode: 'class'模式下，prefers-color-scheme完全被忽略 - 如果用
darkMode: 'media'，则无需手动加dark类，但会失去手动控制能力——二者不可混用
darkMode: 'class' 和 darkMode: 'media' 的行为差异很关键
这是 Tailwind 配置里最易混淆的一点。darkMode 决定了 dark: 前缀如何被解释，不是“支持暗色模式”，而是“按什么信号触发”。
-
darkMode: 'class'：只响应dark类名存在与否；适合需要用户手动开关的场景 -
darkMode: 'media'：只响应prefers-color-scheme: dark媒体查询；适合纯跟随系统、不提供开关的场景 - 配置写成
darkMode: 'class'后，即使用户系统设为深色，页面也不会变暗——这点常被忽略 - 不能同时启用两种逻辑；想兼顾系统偏好 + 手动覆盖，得自己用 JS 监听
prefers-color-scheme并同步设置dark类
手动切换时 localStorage 保存状态是刚需
刷新页面后恢复上次选择，不是可选项，而是实际体验底线。Tailwind 不管这个，得你自己存取。
立即学习“前端免费学习笔记（深入）”；
- 初始化时从
localStorage读：const saved = localStorage.getItem('darkMode')，再决定是否加dark类 - 切换时立刻写入：
localStorage.setItem('darkMode', darkMode ? 'true' : 'false') - 注意 SSR 场景（如 Next.js）：首次渲染时
window未定义，需延迟到客户端执行类名操作，否则服务端和客户端状态不一致导致水合警告 - 别用
cookie或 URL 参数替代localStorage——前者增加请求负担，后者污染分享链接
dark: 与媒体查询混合使用容易出错
有人试图这样写：dark:md:bg-black md:dark:bg-gray-900，以为能组合断点和暗色模式——不行，Tailwind 不支持嵌套条件。每个工具类只能有一个“状态前缀”，dark: 和 md: 是互斥的修饰符。
-
md:dark:bg-gray-900是非法写法，会被忽略 - 正确做法是分开声明：
bg-white dark:bg-gray-900 md:bg-gray-50 md:dark:bg-gray-800 - 如果要基于系统偏好做响应式暗色适配，只能靠 JS 监听
matchMedia('(prefers-color-scheme: dark)')，然后动态加类，不能指望 CSS 工具类自动组合 - 自定义
@layer components时，也别在@apply中混用dark:和响应式前缀——编译会失败或静默丢弃
最常被漏掉的是：暗色模式切换后，<html> 元素的 class 更新了，但表单控件（比如 <input type="range">）、第三方 UI 组件或内联 SVG 的颜色可能仍沿用亮色逻辑——这些地方得单独加 dark: 或用 CSS 变量兜底。
