darkmode 必须显式配置为 'media' 或 'class',否则 dark: 类不生成;需顶层设置、html 元素加 dark 类、同步 localstorage 与 storage 事件监听,并手动补全 dark: 变体。

darkMode 必须显式配置,否则 dark: 类根本不会生成
不配 darkMode,dark:bg-gray-900 这类写法就等于没写——Tailwind 编译时直接跳过所有 dark: 变体,连 CSS 规则都不会输出,更别说生效了。
合法值只有两个:'media' 或 'class'。常见错误包括:
-
darkMode: true、darkMode: 'dark'、darkMode: ''—— 全部无效 - 把
darkMode: 'class'写进theme.extend或plugins里 —— 必须是顶层字段 - TypeScript 配置中类型导出不完整(如漏掉
@types/tailwindcss),导致配置未被读取
正确写法(tailwind.config.js):
/** @type {import('tailwindcss').Config} */
module.exports = {
content: ["./src/**/*.{js,ts,jsx,tsx}"],
darkMode: 'class', // ✅ 必须在这里,不能缩进或嵌套
theme: {
extend: {},
},
plugins: [],
}
class 模式下,dark 类必须加在 上,且得同步设置
Tailwind 只认 document.documentElement(即 元素)有没有 dark 类。加在 上完全无效,尤其在 Next.js/Nuxt 等 SSR 框架中会触发 hydration error。
首屏“闪白”不是 bug,是执行时机问题:CSS 先渲染浅色样式,JS 后加类才切深色。解决方法只有一种:
- 脚本必须内联在
里,不能用DOMContentLoaded或window.onload - 必须用 IIFE 立即执行,且包裹
try/catch(服务端环境无window) - 优先读
localStorage.getItem('theme'),fallback 到window.matchMedia('(prefers-color-scheme: dark)').matches
最小可用初始化脚本:
如果你了解HTML,CSS和JavaScript,您已经拥有所需的工具开发Android应用程序。本动手本书展示了如何使用这些开源web标准设计和建造,可适应任何Android设备的应用程序 - 无需使用Java。您将学习如何创建一个在您选择的平台的Android友好的网络应用程序,然后转换与自由PhoneGap框架到一个原生的Android应用程序。了解为什么设备无关的移动应用是未来的潮流,并开始构建应用程序,提供更
(() => {
try {
const saved = localStorage.getItem('theme')
const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches
const shouldDark = saved === 'dark' || (saved !== 'light' && prefersDark)
document.documentElement.classList.toggle('dark', shouldDark)
} catch {}
})()
dark: 变体要手动补全,没有自动降级
配完 darkMode: 'class' 只是开了门,不代表颜色自动适配。比如 text-gray-700 在深色背景下可能还是灰得看不清,必须显式写成 dark:text-gray-300。
常见疏漏点:
- 按钮禁用态:
disabled:text-gray-400→ 忘写dark:disabled:text-gray-600 - 输入框 focus 状态:
focus:ring-blue-500→ 深色下需dark:focus:ring-blue-400 - 与 hover/focus 组合时顺序不影响功能,但建议统一用
dark:hover:bg-gray-700(先限定模式,再限定交互)
别指望 Tailwind 自动推导深色值——它不做语义映射,只按你写的规则生成 CSS。
切换时状态必须三处同步,否则跨标签页不同步
用户在一个标签页点了暗色开关,刷新或新开标签页又变回亮色,是因为只改了 DOM 类,没持久化状态。
每次切换必须同时操作:
document.documentElement.classList.toggle('dark')localStorage.setItem('theme', isDark ? 'dark' : 'light')- 监听
storage事件,在其他标签页修改时立刻响应
最容易被忽略的是:没有监听 storage 事件。这意味着你关掉当前页再打开,或者在另一个标签页切换主题,当前页不会自动更新 —— 它只会等下次刷新才读 localStorage,中间存在明显延迟。
前端入门到VUE实战笔记:立即使用
在学习笔记中,你将探索 前端 的入门与实战技巧!










