必须手动给<html>加dark类，Tailwind仅通过document.documentElement是否存在dark类判断深色模式，加在<body>或子元素无效；服务端渲染需直出对应class，客户端须用内联脚本在CSS解析前同步设置，避免闪白。
暗黑模式开关怎么加到 HTML 根元素上？
Tailwind 的暗黑模式依赖于 dark: 变体，但它不会自动检测系统主题——你得手动告诉它当前是暗色还是亮色。最直接的方式是给 <html> 元素加一个 dark class。
常见错误是只在 <body> 或某个容器上加 dark，结果 dark:bg-gray-900 之类完全不生效。因为 Tailwind 默认用 class 模式（不是 media 模式），它只检查 <html> 是否含 dark class。
- 在服务端渲染或静态页中，可直接写：
<html class="dark">或<html class="light"> - 客户端切换时，必须操作
document.documentElement.classList，不是document.body - 切换后无需重载 CSS，Tailwind 已预生成所有
dark:*规则，只等 class 生效
怎么让暗黑模式响应系统偏好？
用 window.matchMedia 监听 (prefers-color-scheme: dark) 是最稳妥的初始化方式，但注意：它只触发一次（页面加载时），后续系统主题变更是会触发回调，但你需要主动监听。
- 初始化时读取一次：
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches - 然后设置：
document.documentElement.classList.toggle('dark', isDark) - 再加监听器，避免用户中途改系统设置后 UI 不同步：
const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)'); mediaQuery.addEventListener('change', e => { document.documentElement.classList.toggle('dark', e.matches); }); - 不要用
localStorage覆盖系统偏好，除非用户明确点过“切换”按钮——否则违背用户预期
用户手动切换时如何持久化？
一旦用户点了“切到暗色”，你就该记住这个选择，优先级高于系统偏好。典型做法是：
立即学习“前端免费学习笔记（深入）”；
- 切换时写入
localStorage，key 用color-scheme或类似语义名 - 页面加载时优先读
localStorage.getItem('color-scheme')，值为"dark"或"light"；没值才 fallback 到matchMedia - 注意：首次访问时若 localStorage 为空，不要默认设暗色——这会让亮色用户一进来就黑屏
- 同步更新 class 和 storage：
function setDarkMode(isDark) { document.documentElement.classList.toggle('dark', isDark); localStorage.setItem('color-scheme', isDark ? 'dark' : 'light'); }
为什么有些 dark: 样式不生效？
最常踩的坑是组件内部用了 @apply 但没处理 dark 变体，或者用了第三方组件库自带的 class（比如 bg-white）却没配 dark:bg-gray-900。
-
@apply不支持直接写@apply dark:bg-gray-800——必须拆成两个规则，或改用class属性控制 - 使用
dark:时，确保对应属性本身支持暗色变体（比如text-gray-700有dark:text-gray-300，但text-red-500没配暗色版就得自己加） - 如果用了 CSS-in-JS 或 styled-components，Tailwind 的
dark:不起作用——它只对纯 class 生效 - 开发时打开浏览器 DevTools，确认
<html>确实有darkclass，且目标元素的 class 列表里包含带dark:的完整类名（如dark:bg-gray-900）
暗黑模式真正麻烦的不是开关逻辑，而是每处颜色、阴影、边框、文字对比度都要双份定义；最容易漏的是表单控件、图标颜色、图片占位符，还有第三方 UI 组件的暗色适配——这些没法靠一个 class 解决，得一行行补。
