Tailwind CSS V4 主题系统完全指南（@theme 全新 CSS 主题体系）

Tailwind CSS V4 最大的架构变革：主题系统彻底从 JS 迁移到 CSS。

在 V3 中，我们依赖 tailwind.config.js 写主题、扩展颜色、修改断点；而 V4 完全抛弃 JS 配置优先逻辑，使用原生 CSS 指令 @theme 统一管理所有设计令牌（颜色、字体、间距、圆角、断点、阴影）。

V4 主题更干净、更直观、支持运行时动态切换、天然适配暗色模式、无需重启服务、热更新生效。

本文带你从零吃透 V4 主题系统：扩展主题、覆盖默认主题、清空默认主题、暗色主题、主题变量使用、V3 迁移方案。

一、V4 主题核心变革（V3 VS V4）

1. 核心区别

• V3：主题写在 tailwind.config.js，基于 JS 对象，编译时生效，不支持运行时动态切换
• V4：主题写在 CSS @theme，生成原生 CSS 变量，浏览器运行时可动态修改

2. @theme 能干什么

在 @theme {} 中定义任意「设计令牌」，自动生成对应的工具类：

• 自定义颜色 → 自动生成 text-xxx / bg-xxx / border-xxx
• 自定义字体 → 自动生成 font-xxx
• 自定义断点 → 自动生成 xxx: 响应式前缀
• 自定义圆角、阴影、间距、行高

3. 命名规范（必须记住）

V4 主题变量统一前缀：

• 颜色：--color-*
• 字体：--font-*
• 断点：--breakpoint-*
• 圆角：--radius-*
• 阴影：--shadow-*
• 间距：--spacing-*

二、基础用法：扩展自定义主题

默认保留 Tailwind 全部原生主题，只新增、不覆盖，最常用、最安全的业务写法。

1. 自定义品牌色（多色阶）

@import "tailwindcss";

@theme {
  /* 主品牌色 */
  --color-brand: #165DFF;
  --color-brand-light: #4080ff;
  --color-brand-dark: #0E42D2;

  /* 功能色 */
  --color-success: #00B42A;
  --color-warning: #FF7D00;
  --color-danger: #F53F3F;
}

直接使用：text-brand、bg-brand-light、border-danger

2. 自定义字体、字号、行高

@theme {
  /* 自定义字体栈 */
  --font-sans: "Inter", "system-ui", sans-serif;
  --font-display: "Microsoft Yahei", sans-serif;  /* 自定义超大字号 */
  --text-xxl: 4rem;
}

3. 自定义圆角、阴影、间距

@theme {
  --radius-card: 16px;
  --shadow-card: 0 4px 20px rgba(0,0,0,0.08);
  --spacing-18: 4.5rem;
}

使用：rounded-card、shadow-card、p-18

4. 自定义响应式断点

@theme {
  --breakpoint-xs: 360px;
  --breakpoint-3xl: 1920px;
}

三、进阶：覆盖默认主题

V4 支持直接重写官方默认主题，比如把默认蓝色改成自己的蓝色，全局生效。

@theme {
  /* 覆盖默认蓝色全系 */
  --color-blue-500: #165DFF;
  --color-blue-600: #0E42D2;
}

项目中所有 bg-blue-500、text-blue-500 全局自动替换成自定义色值。

四、高级：清空默认主题（从零自定义）

V4 独有超强能力：一键清空所有默认主题，从零搭建完全自定义设计系统。

@theme {
  /* 清空所有默认主题令牌 */
  --*: initial;  /* 完全自定义一套主题 */
  --color-primary: #165DFF;
  --color-secondary: #6B7280;
  --radius-default: 8px;
}

适合：大型项目、组件库、自定义 Design System。

五、V4 暗色主题最佳方案（原生支持）

V4 无需 JS 配置，纯 CSS 实现亮色/暗色两套主题。

@import "tailwindcss";/* 默认亮色主题 */
@theme {
  --color-bg: #ffffff;
  --color-text: #111827;
}
/* 暗色主题覆盖 */
.dark {
  @theme {
    --color-bg: #0f172a;
    --color-text: #f3f4f6;
  }
}

页面直接使用：bg-bg text-text，自动跟随 dark 模式切换。

六、在自定义 CSS 中使用主题变量

V4 所有主题都会编译为原生 CSS 变量，可以在任意自定义样式中复用。

.custom-box {
    background: var(--color-brand);
    border-radius: var(--radius-card);
    box-shadow: var(--shadow-card);
}

也可以使用 theme() 函数（兼容写法）：

.custom-box {
  color: theme("colors.brand");
}

七、V4 兼容 V3 旧配置（@config）

如果你是老项目迁移，不想重写主题，可以继续使用 tailwind.config.js。

V4 不会自动读取 config，需要手动引入：

@import "tailwindcss";
@config "./tailwind.config.js";

引入后，V3 的 theme、extend、plugins 全部兼容生效。

八、V4 与 V3 主题完整对比表

九、企业级完整主题模板（可直接复用）

@import "tailwindcss";

@theme {
  /* 主品牌色 */
  --color-brand: #165DFF;
  --color-brand-light: #4080ff;
  --color-brand-dark: #0E42D2;

  /* 功能色 */
  --color-success: #00B42A;
  --color-warning: #FF7D00;
  --color-danger: #F53F3F;
}

十、高频避坑总结

• V4 优先用 @theme，尽量抛弃 tailwind.config.js
• 主题变量命名必须带前缀（–color- / –font-），否则不生成工具类
• 修改 @theme 无需重启服务，即时热更新
• 需要动态切换主题（换肤），必须用 V4 CSS 主题，V3 JS 主题无法实现
• 不要混用 V3 extend 写法，V4 统一 @theme 扩展/覆盖

总结

Tailwind CSS V4 的主题系统，完成了从「编译时 JS 配置」到「运行时 CSS 原生配置」的质变。

核心优势：配置更集中、语法更简单、支持动态换肤、热更新更快、适配暗色模式更优雅。

新项目直接全套使用 @theme；老项目可通过 @config 平滑迁移，渐进式升级。

附录：Tailwind CSS V4 @theme 主题系统速查表

提示：V4主题使用@theme指令，定义CSS变量自动生成工具类；变量命名必须带对应前缀；变量会导出为原生CSS变量，JS运行时也能修改，支持动态换肤。

一、主题变量前缀对照表

二、基础扩展模板（保留默认主题，只新增，推荐新项目）

@import "tailwindcss";
@theme {
  /* 自定义颜色 */
  --color-brand: #165DFF;
  --color-brand-light: #4080ff;
  --color-brand-dark: #0E42D2;
  --color-success: #00B42A;
  --color-warning: #FF7D00;
  --color-danger: #F53F3F;
  /* 圆角、阴影 */
  --radius-card: 16px;
  --shadow-card: 0 4px 20px rgba(0,0,0,0.08);
  /* 断点 */
  --breakpoint-xs: 360px;
  --breakpoint-3xl: 1920px;
}

使用示例：

<div class="bg-brand text-white rounded-card shadow-card p-4">品牌卡片</div>

三、覆盖默认主题（修改内置色值）

@theme {
  --color-blue-500: #165DFF;
  --color-blue-600: #0E42D2;
}

页面原有bg-blue-500全部自动替换，全局生效。

四、清空全部默认主题（自建设计系统，组件库用）

@theme {
  --*: initial;  --color-primary: #165DFF;
  --color-secondary: #6B7280;
  --radius-default: 8px;
}

五、暗色模式写法

@import "tailwindcss";@theme {
  --color-bg: #ffffff;
  --color-text: #111827;
}
.dark {
  @theme {
    --color-bg: #0f172a;
    --color-text: #f3f4f6;
  }
}

html添加class="dark"开启暗色：

<body class="dark bg-bg text-text">

六、在自定义CSS里读取主题变量

两种写法，任选其一

/* 原生css变量（推荐，支持运行时动态修改） */
.box {
  background: var(--color-brand);
  border-radius: var(--radius-card);
}/* theme() 兼容写法 */
.box2 {
  color: theme("colors.brand");
}

七、V3旧配置兼容

@import "tailwindcss";
@config "./tailwind.config.js";

引入后可继续读取tailwind.config.js，适合老项目平滑迁移。

八、JS动态修改主题（V4独有能力）

// JS直接修改CSS变量，实现换肤
document.documentElement.style.setProperty('--color-brand', '#722ED1')

九、常用代码片段

1. 自定义字体

@theme {
  --font-sans: "Inter", system-ui, sans-serif;
  --font-display: "Microsoft Yahei", sans-serif;
}

使用：font-display

2. 自定义字号

@theme {
  --text-xxl: 4rem;
}

使用：text-xxl

3. 自定义间距

@theme {
  --spacing-18: 4.5rem;
}

使用：p-18 m-18 gap-18

十、避坑清单

1. 变量前缀不能写错，--color-xxx少写color，不会生成工具类。
2. @theme写在CSS文件内，不是JS文件；修改无需重启dev服务，热更新。
3. --*: initial会清空全部内置主题，谨慎使用，一般只有组件库才需要。
4. 暗色模式：.dark是类名，需要JS切换html上的dark类名，Tailwind不会自动检测系统prefers-color-scheme（如需自动检测可搭配媒体查询）。
5. @theme内定义的变量是CSS自定义属性，可以JS动态修改，这是V4相比V3最大优势。
6. 不要同时大量混用@config和@theme，容易出现主题冲突。