darkMode配置项必须写在tailwind.config.js的darkMode字段，仅支持'class'或'media'；配'class'需手动给html加dark类，配'media'则响应系统偏好，不可混用。
darkMode配置项写在哪？不是tailwind.config.js里随便放就行
Tailwind的暗黑模式开关必须显式声明在tailwind.config.js的darkMode字段，且只接受两个值：'class'或'media'。写成'dark'、true或漏掉这个字段，都会让dark:前缀完全失效——你写的dark:bg-gray-800会被直接忽略，连警告都不报。
常见错误是以为加了darkMode: 'class'就万事大吉，其实还差关键一步：手动给根元素加dark类。浏览器不会自动帮你加，也不读系统偏好（那是media干的事）。
-
darkMode: 'class'→ 依赖你在或上手动控制class="dark" -
darkMode: 'media'→ 自动响应prefers-color-scheme: dark，但无法用JS切换，纯靠系统设置 - 别混用：比如配了
'class'又监听prefers-color-scheme改class，可以，但darkMode本身不能写'class' | 'media'这种联合值
怎么用JS切换暗黑模式？别直接操作document.body.classList
直接document.body.classList.toggle('dark')看似简单，但有三个实际问题：刷新丢失状态、服务端渲染（SSR）下首屏闪白、不兼容Next.js等框架的Hydration逻辑。正确做法是把暗黑状态存进localStorage，并在页面加载时同步到元素（不是），因为Tailwind默认查的是html上的dark类。
示例逻辑（无需框架）：
立即学习“前端免费学习笔记（深入）”；
if (localStorage.theme === 'dark' || (!('theme' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches)) {
document.documentElement.classList.add('dark')
} else {
document.documentElement.classList.remove('dark')
}
切换时只改localStorage和document.documentElement，不碰body。这样Next.js、Nuxt都能正确hydrate，也避免CSS闪动。
dark:前缀不生效？检查是否用了@layer components封装
如果你把带dark:的样式写在@layer components里，而组件本身没被@apply调用，或者用在了未启用暗黑模式的上下文（比如某个子组件强制覆盖了dark:规则），它就不会生效。更隐蔽的问题是：某些插件（如@tailwindcss/forms）自带的暗黑样式，会和你的dark:规则冲突。
- 确认
dark:类确实生成到了CSS中：搜索编译后的CSS文件里有没有.dark .your-class或.your-class.dark结构 - 避免在
@layer utilities外写dark:变体——Tailwind只对已注册的工具类才生成变体 - 第三方插件的暗黑支持不一定开启：比如
@tailwindcss/typography要额外加dark:prose-invert，不是自动适配
为什么dark:bg-black在light模式下还显示黑色？
这不是Tailwind的bug，是你误解了“条件应用”的逻辑。dark:bg-black只在dark类存在时启用，但它**不取消**bg-white或其他基础背景色。如果同时写了bg-white dark:bg-black，那在暗黑模式下bg-white依然存在，只是被dark:bg-black覆盖（因为CSS特异性相同，后者后出现）。但如果只写dark:bg-black，没有基础背景色，那在light模式下背景就是透明的，可能露出父容器颜色，看起来像“意外变黑”。
- 必须成对写：需要明确light和dark两套值，例如
bg-white dark:bg-gray-900 - 别依赖“默认值”：Tailwind不会帮你回退到浏览器默认背景，不写
bg-就是background-color: transparent - 调试技巧：打开开发者工具，勾选
html.dark模拟暗黑状态，看对应元素的computed styles里background-color是否真的变了
暗黑模式真正的复杂点不在配置，而在状态同步时机和CSS层叠顺序——这两个地方一错，表现就不可预测，而且很难一眼看出原因。
