darkMode: 'class' 是 Tailwind 启用基于 CSS 类的深色模式策略，需手动在 <html> 添加 dark 类才生效；仅改配置不操作 DOM、不持久化状态、不初始化类，dark:样式不会触发。
darkMode: 'class' 是什么，为什么不能只改配置就生效
配置 darkMode: 'class' 只是告诉 Tailwind 别自动监听系统偏好，转而等待你手动在 HTML 根元素上添加 dark 类。它本身不生成切换逻辑，也不操作 DOM —— 这部分必须你自己写。
常见错误是改完 tailwind.config.js 就以为暗黑模式能自动切换，结果页面始终亮色，连 dark:bg-gray-800 都不生效。根本原因是：HTML 上没 class="dark"，Tailwind 没东西可匹配。
- 必须确保初始 HTML 的
<html>或<body>元素带class="dark"（暗色）或不含（亮色） - 切换时要显式增删
dark类，且推荐操作<html>元素，避免嵌套组件样式被意外覆盖 - 别用
localStorage存状态却不读取 —— 页面刷新后会丢失上次选择
如何用 JavaScript 安全地切换 dark class
最简但可靠的方案是封装一个函数，统一处理 class 增删、存储和同步到文档根节点。关键点不是“加 class”，而是“加对地方 + 记住选择 + 不干扰 SSR”。
- 优先操作
document.documentElement（即<html>），不是document.body - 用
localStorage保存用户偏好，键名建议固定为darkMode - 初始化时先读
localStorage，再设置 class；避免闪屏（比如系统是亮色但用户上次选了暗色，得立刻应用） - 不要用
classList.toggle()直接切换 —— 它依赖当前状态，而初始状态可能未从存储加载完成，导致误判
示例逻辑：
立即学习“前端免费学习笔记（深入）”；
function setDarkMode(isDark) {
if (isDark) {
document.documentElement.classList.add('dark');
} else {
document.documentElement.classList.remove('dark');
}
localStorage.setItem('darkMode', isDark);
}
<p>// 初始化
const saved = localStorage.getItem('darkMode');
if (saved !== null) {
setDarkMode(saved === 'true');
} else {
// 默认回退到系统偏好（可选）
setDarkMode(window.matchMedia('(prefers-color-scheme: dark)').matches);
}为什么 dark:bg-* 类在 class 模式下仍不生效
除了没加 dark 类，还有几个高频硬伤：
-
darkMode: 'class'必须写在tailwind.config.js的顶层darkMode字段，不是theme里，也不是插件配置中 - 修改配置后必须重启构建工具（如
npm run dev），Tailwind 不热更配置项 - CSS 文件未正确引入或被其他样式覆盖 —— 检查浏览器开发者工具中，
.dark .dark\:bg-gray-800是否出现在 computed styles 里 - 用了
@layer components但忘了加@apply dark:bg-gray-800，或者在@layer utilities中定义时漏了dark:变体
服务端渲染（SSR）或静态站点中要注意什么
Next.js、Nuxt 或 Astro 等框架下，JS 还没执行时 HTML 已渲染完毕，如果服务端没同步暗色状态，首屏会闪烁或错乱。
- Next.js 中，可在
getServerSideProps或generateStaticParams里读取请求头sec-ch-ua-prefers-color-scheme（不通用），更可靠的是前端初始化时立即应用 localStorage 值，并用useEffect+useState控制组件重绘 - 纯静态站点（如 Hugo、Jekyll）无法服务端判断用户偏好，只能靠 JS 初始化时快速 patch
<html>class，配合data-theme属性做 CSS 阻塞加载优化 - 避免在
useEffect外直接操作 DOM —— SSR 环境下document不存在，会报错
真正难的不是加一行 darkMode: 'class'，而是让 class 出现在对的时机、对的节点、并跨刷新持久化。多数问题卡在这三步的任意一环。
