Tailwind CSS v4类名式深色主题无需dark前缀配置失效问题

核心解决方案 #

Tailwind v4不支持@theme dark:这类语法，正确的做法是通过.dark选择器嵌套@theme规则来覆盖基础变量，搭配darkMode: 'class'配置，实现单个类自动适配深浅两种主题。

完整配置示例 #

1. CSS文件配置（如index.css）

@import 'tailwindcss';
@plugin '@tailwindcss/forms';
@plugin '@tailwindcss/container-queries';

/* 基础浅色主题变量 */
@theme {
  --color-bgContrast: #f9f9f9;
  --color-primary100: #0A7280;
  --color-primary50: #BAD7DB;
  --color-bgBase: #FDFDFD;
}

/* 深色主题变量覆盖 */
.dark {
  @theme {
    --color-bgContrast: #66C8B6;
    --color-primary100: #054f58;
    --color-primary50: #8cb8bc;
    --color-bgBase: #1a1a1a;
  }
}

2. Tailwind配置文件（tailwind.config.js）

export default {
  // 启用class模式的深色切换
  darkMode: 'class',
  content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"],
  theme: {
    extend: {
      colors: {
        // 将CSS变量映射为Tailwind可识别的颜色类
        primary100: 'var(--color-primary100)',
        primary50: 'var(--color-primary50)',
        bgBase: 'var(--color-bgBase)',
        bgContrast: 'var(--color-bgContrast)'
      }
    }
  }
}

关键说明 #

• 变量覆盖逻辑：当<html>标签添加dark类时，.dark选择器内的@theme变量优先级更高，会自动覆盖基础主题变量，因此bg-bgContrast这类类无需额外添加dark:前缀就能自动切换颜色。
• darkMode设置：Tailwind v4默认深色模式为media（跟随系统设置），必须手动配置为class才能识别自定义的.dark类切换逻辑。
• 无需自定义变体：不需要额外定义@custom-variant dark，默认的dark变体已经适配了.dark类的作用范围，除非你需要自定义更复杂的选择器规则。

使用方式 #

切换深色模式时，只需给<html>标签添加或移除dark类即可：

<!-- 浅色模式 -->
<html>
<!-- 深色模式 -->
<html class="dark">

内容的提问来源于stack exchange，提问作者pierre.b