Skip to main content

Tailwindcss v4 的 @import / @theme / @utility 指令是什么？

· 5 min read

Tailwind v4 重新设计 CSS 入口,几条新指令各司其职,不再像 v3 那样靠 @tailwind 堆叠。

  1. @import "tailwindcss":替代 v3 的三条 @tailwind,整合 base + utilities
  2. @theme:设计 token 入口,颜色字号间距都在这定义
  3. @utility:自定义工具类,替代 v3 的 @layer 写法
  4. @variant:自定义变体(hover / focus / ...),替代 v3 的 JS 配置
  5. 级联顺序:v4 只剩 base → utilities 两层

核心:@theme 把设计 token 从 JS 搬到 CSS,样式与变量同源。

一句话总结 v4 的指令体系​

v4 把 v3 的三条 @tailwind 拆出来,重新设计为几条独立指令,各管一摊。最大的变化是 @theme——设计 token 不再藏在 tailwind.config.js 里,直接写在 CSS 文件。

@import "tailwindcss"​

替代 v3 的三条 @tailwind 指令。一条 import 整合所有层。

/* v4 写法 */
@import "tailwindcss";

替代 v3 的:

/* v3 写法 */
@tailwind base;
@tailwind components;
@tailwind utilities;

@theme —— v4 真正的杀手锏​

这一节是 v4 改动的核心。@theme 块用来定义设计 token——颜色、字号、间距、圆角、字体等。v3 这些配置都写在 tailwind.config.js 里,v4 直接搬进 CSS 文件。

基本用法​

@import "tailwindcss";

@theme {
  /* 颜色 */
  --color-primary: oklch(60% 0.18 240);
  --color-secondary: oklch(80% 0.1 100);

  /* 字号 */
  --text-base: 1rem;
  --text-2xl: 1.5rem;

  /* 间距 */
  --spacing-4: 1rem;

  /* 圆角 */
  --radius-md: 0.375rem;

  /* 字体 */
  --font-sans: 'Inter', sans-serif;
}

写完上面这一段,源码里就能直接用 bg-primary、text-2xl、p-4、rounded-md、font-sans 这些类——Tailwind 构建时扫到这些 CSS 变量,自动生成对应 utility。

命名空间自动生成 utility​

@theme 里的 CSS 变量 不是普通变量,命名空间会被 Tailwind 扫到并转成对应 utility:

变量前缀生成的 utility例子
--color-*bg- text- border- ring---color-primary → bg-primary、text-primary
--text-*text---text-2xl → text-2xl(字号,不是颜色)
--font-*font---font-sans → font-sans
--spacing-*p- m- w- h- 等所有尺寸--spacing-4 → p-4、m-4、w-4
--radius-*rounded---radius-md → rounded-md
--shadow-*shadow---shadow-lg → shadow-lg
--breakpoint-*@ 用于 @media--breakpoint-md → @md

注意 --text-* 既生成字号 utility 又不生成颜色 utility——具体看变量名,后缀名决定。

@theme 的核心价值​

  • 设计 token 跟 CSS 写在同处——v3 时代写在 tailwind.config.js 里跟 CSS 分离,改个颜色得动 JS
  • CSS 变量原生支持——运行时可被 JS 改写,做主题切换不再需要 darkMode: 'class' 整套机制
  • 构建期自动转 utility——写一个 --color-brand 就自动有 bg-brand、text-brand 等

主题切换:@theme 时代很简单​

v4 不需要 dark: 前缀那一套,纯 CSS 变量就能搞定:

@theme {
  --color-bg: white;
  --color-fg: #111;
}

@media (prefers-color-scheme: dark) {
  :root {
    --color-bg: #111;
    --color-fg: white;
  }
}

然后源码里写 bg-bg、text-fg,浏览器自动跟系统主题切换。

@utility —— 自定义工具类​

v3 的 @layer utilities { .x { ... } } 在 v4 直接用 @utility:

@utility scrollbar-hide {
  scrollbar-width: none;
  &::-webkit-scrollbar { display: none; }
}

或者 @apply 风格:

@utility btn-primary {
  @apply bg-blue-500 text-white px-4 py-2 rounded;
}

源码里直接用:

<div class="scrollbar-hide">
<button class="btn-primary">提交</button>

@variant —— 自定义变体​

v3 的 dark:、hover: 等变体需要在 tailwind.config.js 配置。v4 全部 CSS 化:

@variant hocus (&:hover, &:focus);
@variant not-first (&:not(:first-child));

源码里:

<button class="hocus:bg-blue-700">...</button>
<p class="not-first:mt-4">...</p>

v4 的级联顺序只剩两层​

v3 是 theme → base → components → utilities 四层;v4 只剩 base → utilities 两层。components 删了(被 @utility 取代),theme 不在级联顺序里——它只定义 token,不输出样式。

v3 → v4 写法对照表​

维度v3 写法v4 写法
加载层@tailwind base; @tailwind components; @tailwind utilities;@import "tailwindcss";
设计 tokentailwind.config.js 的 theme: { ... }CSS 文件里的 @theme { ... }
自定义 utility@layer utilities { .x { ... } }@utility x { ... }
自定义 component@layer components { .btn { @apply ... } }@utility btn { @apply ... }
自定义变体tailwind.config.js 的 variants: { ... }@variant hocus (&:hover, &:focus);

一个常见埋雷:@import 顺序​

顺序错了 token 全部失效

@import "tailwindcss" 必须先,因为它会先扫 @theme 块并注册 token;反过来,token 就成了未定义变量,后续 utility 全部失效。

/* ❌ 顺序错了 */
@theme {
  --color-primary: blue;
}
@import "tailwindcss";

/* ✅ @import 必须先 */
@import "tailwindcss";

@theme {
  --color-primary: blue;
}

一句话总结​

v4 几条指令的分工:

  • @import "tailwindcss" = 加载所有层(替代 v3 三条 @tailwind)
  • @theme = 设计 token 入口,token 与 CSS 同源
  • @utility = 自定义工具类(替代 v3 @layer)
  • @variant = 自定义变体(替代 v3 JS 配置)

记住:@import 先,@theme 跟着,然后是 @utility / @variant 自由穿插。

Reference​

  1. Tailwind CSS v4 Theme 文档
  2. Tailwind CSS v4 Functions and Directives
  3. Tailwind CSS v4 Upgrade Guide
  4. Preflight 源码