Tailwind CSS 全局主题配置及使用

发表于 更新于 分类于
Tailwind CSS v4 中 @theme 变量与工具类的对应关系，以及项目实战配置示例

前言

Tailwind CSS v4 推荐在 CSS 里用 @theme 块定义设计 token，替代 v3 时代 tailwind.config.ts 里大量的 theme.extend。

本文说明 @theme 变量名 和 模板里实际使用的工具类 如何对应，并附一个 Vue 项目中的真实配置示例。

核心规则

一句话记：

--{命名空间}-{名称} → 工具类 {前缀}-{名称}

Tailwind 读取 @theme 中的 CSS 变量，自动生成对应的工具类。变量名去掉 -- 和命名空间后，剩余部分就是类名里的 token。

1
2
3
@theme {
  --color-brand: #15d283;
}

使用

1
<div class="bg-brand text-brand border-brand">

命名空间对照表

@theme 变量前缀 工具类前缀 作用
--color-* text- / bg- / border- / fill- 等 颜色
--font-* font- 字体族
--text-* text- 字号
--width-* w- 宽度
--min-width-* min-w- 最小宽度
--max-width-* max-w- 最大宽度
--height-* h- 高度
--min-height-* min-h- 最小高度
--radius-* rounded- 圆角
--shadow-* shadow- 阴影
--background-image-* bg- 背景图 / 渐变

同一个 token 名，配合不同前缀，表达不同 CSS 属性。

例如 --color-brand 既可以是 bg-brand，也可以是 text-brand、border-brand。

项目示例

src/assets/css/style.css：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
@import "tailwindcss/theme" layer(theme);
@import "tailwindcss/utilities" layer(utilities);
@config "../../../tailwind.config.ts";

@theme {
  /* 品牌色 */
  --color-brand: #15d283;
  --color-brand-hover: #2ea890;
  --color-brand-dark: #2ba08c;

  /* 强调色 */
  --color-accent-blue: #4d9ff6;
  --color-accent-teal: #45b7a4;

  /* 表面色 */
  --color-surface-page: #f3f3f3;
  --color-surface-stat: #e7edf6;
  --color-surface-muted: #7f8795;

  /* 宽度（rem，基准 16px） */
  --width-22: 5.5rem;
  --min-width-22: 5.5rem;
  --min-width-37: 9.25rem;
  --min-width-50: 12.5rem;

  /* 容器最大宽度（px，对齐设计稿） */
  --max-width-content: 1200px;
  --max-width-135: 540px;
  --max-width-300: 1200px;

  /* 高度（rem） */
  --height-107.5: 26.875rem;
  --min-height-33: 8.25rem;

  /* 字号（rem） */
  --text-4.4: 1.1rem;
  --text-14: 3.5rem;
  
  /* 圆角（rem） */
  --radius-2.5: 0.625rem;

  /* 阴影（px） */
  --shadow-cap: 0 10px 28px rgba(77, 159, 246, 0.1);
  --shadow-cap-featured: 0 6px 20px rgba(77, 159, 246, 0.12);

  /* 字体 */
  --font-sans: 'HarmonyOS Sans SC', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
    'PingFang SC', 'Microsoft YaHei', sans-serif;

  /* 渐变背景 */
  --background-image-text-brand: linear-gradient(90deg, #3085ff 0%, #15d283 100%);
  --background-image-text-sunset: linear-gradient(to right, #fa709a 0%, #fee140 100%);
  --background-image-btn-type-1: linear-gradient(90deg, #e6efff 0%, #fdf5ff 100%);
}

颜色

@theme 变量 模板中的类名
--color-brand bg-brand、text-brand、border-brand
--color-brand-hover bg-brand-hover、text-brand-hover、hover:text-brand-hover
--color-surface-muted text-surface-muted、bg-surface-page
--color-accent-blue border-accent-blue、text-accent-blue 
1
2
3
<button class="bg-brand text-white hover:bg-brand-hover">
<p class="text-surface-muted">
<div class="border border-accent-blue shadow-cap">

字号 vs 颜色

text- 前缀既用于颜色，也用于字号，Tailwind 靠命名空间区分，不会冲突：

@theme 变量 类名 含义
--color-brand text-brand 文字颜色
--text-3.25 text-3.25 文字大小（0.8125rem ≈ 13px）
--text-3.75 text-3.75 0.9375rem ≈ 15px
--text-4.25 text-4.25 1.0625rem ≈ 17px 
1
2
<span class="text-3.25 text-surface-muted">13px 灰色说明文字</span>
<h2 class="text-4.25 font-bold text-brand">17px 品牌色标题</h2>

尺寸

@theme 变量 类名 换算（16px = 1rem）
--max-width-content: 1200px max-w-content 容器宽度，保留 px
--max-width-300: 1200px max-w-300 同上
--min-width-37: 9.25rem min-w-37 148px
--min-width-50: 12.5rem min-w-50 200px
--width-22: 5.5rem w-22 88px
--height-107.5: 26.875rem h-107.5 430px 
1
2
3
<div class="mx-auto max-w-content">
<section class="h-107.5 w-full">
<button class="min-w-37">按钮</button>

圆角与阴影

@theme 变量 类名
--radius-2.5: 0.625rem rounded-2.5
--shadow-cap shadow-cap
--shadow-cap-featured shadow-cap-featured 
1
<div class="rounded-2.5 shadow-cap hover:shadow-cap-featured">

渐变背景

@theme 变量 类名
--background-image-text-brand bg-text-brand
--background-image-btn-type-1 bg-btn-type-1

变量名去掉 --background-image- 前缀，前面加上 bg- 即为类名。

1
2
3
4
5
<!-- 渐变文字 -->
<h1 class="bg-text-brand bg-clip-text text-transparent">标题</h1>

<!-- 渐变按钮背景 -->
<div class="bg-btn-type-1">标签</div>

字体

@theme 变量 类名 / 用法
--font-sans font-sans，或 body { font-family: var(--font-sans); }

从 v3 config 到 @theme

v3 的嵌套对象在 @theme 里写成扁平变量名：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
// tailwind.config.ts (v3)
theme: {
  extend: {
    colors: {
      brand: {
        DEFAULT: '#15d283',
        hover: '#2ea890',
      },
      surface: {
        page: '#f3f3f3',
      },
    },
  },
}

V4

1
2
3
4
5
6
/* @theme (v4) */
@theme {
  --color-brand: #15d283;
  --color-brand-hover: #2ea890;
  --color-surface-page: #f3f3f3;
}

对比

v3 路径 @theme 变量 类名
colors.brand.DEFAULT --color-brand bg-brand
colors.brand.hover --color-brand-hover bg-brand-hover
colors.surface.page --color-surface-page bg-surface-page
maxWidth.content --max-width-content max-w-content
backgroundImage['text-brand'] --background-image-text-brand bg-text-brand

单位建议

类型 推荐单位 原因
字号 rem 随用户浏览器字号缩放，可访问性更好
组件宽高、间距 rem 与 Tailwind 默认刻度一致
容器 max-width px 对齐设计稿，直观
布局断点（如 min-width: 1280px） px 表示最小支持宽度
阴影 px 通常不随字号缩放

换算基准：16px = 1rem。

小数点 token 要不要转义

不需要。CSS 自定义属性名里 . 是合法字符，直接写即可：

1
2
3
4
5
6
7
/* ✅ 推荐 */
--radius-2.5: 0.625rem;
--text-3.25: 0.8125rem;
--height-107.5: 26.875rem;

/* ❌ 不必 */
--radius-2\.5: 0.625rem;

对应类名：rounded-2.5、text-3.25、h-107.5。

配置文件分工（v4）

文件 职责
tailwind.config.ts 构建配置：content 扫描路径、插件等
src/assets/css/style.css 设计 token：@theme、reset、body 全局样式

设计 token 统一放 @theme，避免两处重复定义导致颜色不一致。

如何验证是否生效

  1. 模板里写类名，如 bg-brand text-3.25
  2. 浏览器 DevTools → 选中元素 → Computed
  3. 查看是否使用了 --color-brand、--text-3.25 等变量

快速自查

  1. 找到 @theme 变量：--{namespace}-{token}
  2. 确定要什么 CSS 属性，选对应前缀（颜色用 bg-/text-，宽度用 max-w- 等）
  3. 拼成 {前缀}-{token}

例如新增品牌辅助色：

1
2
3
@theme {
  --color-brand-light: #e8faf3;
}
1
<div class="bg-brand-light">