Tailwind CSS暗黑模式配置异常：dark:类始终处于激活状态

环境与配置 #

• TailwindCSS版本：

{
  "dependencies": {
    "tailwindcss": "^4.1.3",
  }
}

项目配置文件：

/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: 'class',
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [],
};

代码使用情况 #

组件中暗黑模式工具类的使用：

<div className="bg-white text-black dark:bg-black dark:text-white">
  Hello
</div>

暗黑模式切换逻辑：

const root = document.documentElement;
root.classList.toggle('dark', themeMode === 'dark');
localStorageUtil.setMode(themeMode);

问题现象 #

即使根元素上没有dark类，dark:前缀的样式（如dark:bg-black）仍会被自动应用，仿佛暗黑模式始终处于启用状态。

解决方法 #

Tailwind CSS v4 对暗黑模式的配置语法进行了调整，原darkMode: 'class'配置已失效，需修改为指定选择器的形式：

/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: { selector: '.dark' }, // 替换原有的 'class' 配置
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {},
  },
  plugins: [],
};

修改配置后重新构建项目，此时只有当根元素存在.dark类时，dark:前缀的样式才会生效。

另外可检查是否有其他代码意外给根元素添加了dark类，或浏览器本地存储中是否残留错误的主题模式值，导致切换逻辑异常。

内容的提问来源于stack exchange，提问作者Vin