Tailwind CSS v4 深入：基于 Rust 的新引擎与零配置体验

前言：Tailwind 的进化之路#

Tailwind CSS 自 2017 年诞生以来，从一个争议性的 utility-first 框架成长为前端最流行的 CSS 方案之一。每一个大版本都带来了显著的改进：

v1：确立 utility-first 理念
v2：JIT（Just-In-Time）引擎，按需生成
v3：JIT 成为默认，任意值语法 []，原生嵌套
v4：全面重写——用 Rust 重建引擎，CSS-first 配置，零配置体验

Tailwind CSS v4 不是一次增量更新，而是一次从底层架构到使用方式的全面革新。本文将深入剖析 v4 的核心变化、迁移策略和最佳实践。

从 JavaScript 到 Rust：新引擎 Oxide#

为什么用 Rust 重写？#

Tailwind v3 的引擎完全用 JavaScript（Node.js）编写。虽然 JIT 模式已经很快了，但随着项目规模增长，构建时间仍然是痛点。v4 的引擎代号 Oxide，使用 Rust 编写核心逻辑，通过 NAPI-RS 桥接到 Node.js。

性能提升是惊人的：

指标	v3	v4	提升
全量构建（大型项目）	~800ms	~100ms	8x
增量构建	~200ms	~5ms	40x
内存占用	~150MB	~20MB	7.5x

这不仅仅是”快了一点”——对于大型项目来说，这意味着 HMR（热模块替换）几乎是瞬时的。

Lightning CSS 集成#

v4 内置了 Lightning CSS（同样由 Rust 编写）作为 CSS 解析器和转换器，替代了之前的 PostCSS + Autoprefixer 组合。

Lightning CSS 提供：

CSS 解析和序列化：比 PostCSS 快 100 倍以上
自动浏览器前缀：不再需要 Autoprefixer
CSS 嵌套降级：自动将原生 CSS 嵌套转换为兼容语法
CSS 模块：原生支持
代码压缩：内置 minification，不再需要 cssnano

1
/* 你写的代码 */
2
.card {
3
  display: flex;
4
  user-select: none;
5

6
  &:hover {
7
    transform: scale(1.02);
8
  }
9

10
  & .title {
11
    color: oklch(0.6 0.2 250);
12
  }
13
}
14

15
/* Lightning CSS 自动输出（针对目标浏览器） */
16
.card {
17
  display: -webkit-box;
18
  display: -ms-flexbox;
19
  display: flex;
20
  -webkit-user-select: none;
21
  -ms-user-select: none;
22
  user-select: none;
23
}
24
.card:hover {
25
  -webkit-transform: scale(1.02);
26
  transform: scale(1.02);
27
}
28
.card .title {
29
  color: rgb(0, 119, 255);
30
}

不再需要 PostCSS#

v4 最大的架构变化之一：PostCSS 不再是必需的依赖。

1
# v3 的 postcss.config.js
2
 module.exports = {
3
   plugins: {
4
     tailwindcss: {},
5
     autoprefixer: {},
6
   },
7
 }
8

9
# v4：不需要 PostCSS 配置文件
10
# Tailwind 自己处理一切

当然，如果你仍然需要 PostCSS 生态中的其他插件，v4 也提供了 PostCSS 插件模式作为兼容方案。

CSS-First 配置：告别 tailwind.config.js#

从 JS 配置到 CSS 配置#

v3 中，所有配置都在 tailwind.config.js 中：

1
module.exports = {
2
  content: ['./src/**/*.{html,js,vue}'],
3
  theme: {
4
    extend: {
5
      colors: {
6
        brand: {
7
          50: '#eff6ff',
8
          500: '#3b82f6',
9
          900: '#1e3a5f',
10
        },
11
      },
12
      fontFamily: {
13
        sans: ['Inter', 'system-ui', 'sans-serif'],
14
      },
15
      spacing: {
16
        '18': '4.5rem',
17
      },
18
    },
19
  },
20
  plugins: [
21
    require('@tailwindcss/typography'),
22
  ],
23
};

v4 中，配置直接写在 CSS 文件里：

1
@import "tailwindcss";
2

3
@theme {
4
  --color-brand-50: #eff6ff;
5
  --color-brand-500: #3b82f6;
6
  --color-brand-900: #1e3a5f;
7

8
  --font-sans: "Inter", system-ui, sans-serif;
9

10
  --spacing-18: 4.5rem;
11
}

就这样。没有 JS 配置文件。 Tailwind 直接从你的 CSS 中读取配置。

@theme 详解#

@theme 是 v4 引入的新 at-rule，用于定义设计令牌（design tokens）。它本质上是在定义 CSS 自定义属性，但 Tailwind 会识别这些变量并自动生成对应的 utility classes。

1
@import "tailwindcss";
2

3
@theme {
4
  /* 颜色 —— 自动生成 bg-primary, text-primary, border-primary 等 */
5
  --color-primary: #3b82f6;
6
  --color-secondary: #8b5cf6;
7
  --color-accent: #f59e0b;
8

9
  /* 间距 —— 自动生成 p-xs, m-xs, gap-xs 等 */
10
  --spacing-xs: 0.25rem;
11
  --spacing-sm: 0.5rem;
12
  --spacing-md: 1rem;
13
  --spacing-lg: 2rem;
14
  --spacing-xl: 4rem;
15

16
  /* 圆角 —— 自动生成 rounded-card 等 */
17
  --radius-card: 12px;
18
  --radius-button: 8px;
19
  --radius-pill: 9999px;
20

21
  /* 阴影 —— 自动生成 shadow-soft 等 */
22
  --shadow-soft: 0 2px 8px rgba(0, 0, 0, 0.08);
23
  --shadow-medium: 0 4px 16px rgba(0, 0, 0, 0.12);
24
  --shadow-strong: 0 8px 32px rgba(0, 0, 0, 0.2);
25

26
  /* 字体大小 */
27
  --text-display: 3.5rem;
28
  --text-heading: 2rem;
29
  --text-body: 1rem;
30
  --text-caption: 0.875rem;
31

32
  /* 行高 */
33
  --leading-display: 1.1;
34
  --leading-heading: 1.3;
35
  --leading-body: 1.7;
36

37
  /* 断点 */
38
  --breakpoint-sm: 640px;
39
  --breakpoint-md: 768px;
40
  --breakpoint-lg: 1024px;
41
  --breakpoint-xl: 1280px;
42

43
  /* 动画 */
44
  --ease-spring: cubic-bezier(0.2, 0, 0, 1);
45
  --ease-bounce: cubic-bezier(0.68, -0.55, 0.27, 1.55);
46
}

定义完后，你可以直接使用这些生成的 utility classes：

1
<div class="bg-primary text-white p-lg rounded-card shadow-soft">
2
  <h1 class="text-display leading-display">标题</h1>
3
  <p class="text-body leading-body text-secondary">内容</p>
4
  <button class="bg-accent rounded-button px-md py-sm">
5
    按钮
6
  </button>
7
</div>

覆盖默认主题#

1
@import "tailwindcss";
2

3
@theme {
4
  /* 完全替换默认颜色（使用 --color-* 前缀） */
5
  --color-*: initial; /* 清除所有默认颜色 */
6

7
  /* 定义你自己的颜色系统 */
8
  --color-base: #1a1a2e;
9
  --color-surface: #16213e;
10
  --color-overlay: #0f3460;
11
  --color-primary: #e94560;
12
  --color-text: #eaeaea;
13
  --color-muted: #a0a0b0;
14
}

使用 --<namespace>-*: initial 可以清除该命名空间下的所有默认值，实现完全自定义。

暗色模式#

v4 的暗色模式配置也变为 CSS-first：

1
@import "tailwindcss";
2

3
@theme {
4
  --color-bg: #ffffff;
5
  --color-text: #1a1a2e;
6
  --color-card: #f8fafc;
7
}
8

9
/* 暗色模式变量 */
10
@media (prefers-color-scheme: dark) {
11
  @theme {
12
    --color-bg: #0f172a;
13
    --color-text: #e2e8f0;
14
    --color-card: #1e293b;
15
  }
16
}

或者使用 class 策略：

1
@import "tailwindcss";
2

3
@variant dark (&:where(.dark, .dark *));

这让 dark: 变体生效于 .dark 类下：

1
<html class="dark">
2
  <body class="bg-bg text-text">
3
    <div class="bg-card dark:bg-card">
4
      <!-- 内容 -->
5
    </div>
6
  </body>
7
</html>

零配置自动内容检测#

告别 content 配置#

v3 中你必须显式指定内容扫描路径：

1
// v3
2
module.exports = {
3
  content: [
4
    './src/**/*.{html,js,ts,vue,svelte}',
5
    './index.html',
6
  ],
7
};

v4 自动检测项目中的模板文件。它会：

读取项目的 package.json 和构建工具配置
自动识别框架（Vue、Svelte、Astro 等）
扫描相关源文件中的 class 使用

你不需要配置任何 content 路径。

如果需要手动指定（例如包含外部目录），可以在 CSS 中使用 @source：

1
@import "tailwindcss";
2

3
/* 额外扫描路径 */
4
@source "../shared-components/**/*.vue";
5
@source "../content/**/*.md";

如果需要排除某些路径：

1
@source not "./src/legacy/**";

新的导入方式#

简化导入#

v3 需要三行导入：

1
/* v3 */
2
@tailwind base;
3
@tailwind components;
4
@tailwind utilities;

v4 只需一行：

1
/* v4 */
2
@import "tailwindcss";

如果你需要在各层之间插入自定义样式，可以使用分层导入：

1
@import "tailwindcss/preflight" layer(base);
2
@import "tailwindcss/utilities" layer(utilities);
3

4
/* 在 base 和 utilities 之间插入自定义样式 */
5
@layer base {
6
  body {
7
    font-family: var(--font-sans);
8
    color: var(--color-text);
9
    background: var(--color-bg);
10
  }
11

12
  h1, h2, h3 {
13
    font-weight: 700;
14
    line-height: var(--leading-heading);
15
  }
16
}

新功能与语法变化#

新的 3D Transform Utilities#

v4 新增了 3D 变换相关的 utility classes：

1
<!-- 3D 变换 -->
2
<div class="rotate-x-45 rotate-y-30 perspective-800">
3
  3D 旋转的元素
4
</div>
5

6
<!-- 背面可见性 -->
7
<div class="backface-hidden">
8
  翻转卡片的正面
9
</div>
10

11
<!-- 变换风格 -->
12
<div class="transform-3d">
13
  保持 3D 变换上下文
14
</div>

改进的渐变语法#

1
<!-- 线性渐变 -->
2
<div class="bg-linear-to-r from-blue-500 to-purple-500">
3
  线性渐变
4
</div>
5

6
<!-- 圆锥渐变（新增） -->
7
<div class="bg-conic from-red-500 via-yellow-500 to-green-500">
8
  圆锥渐变
9
</div>
10

11
<!-- 径向渐变 -->
12
<div class="bg-radial from-white to-gray-200">
13
  径向渐变
14
</div>

容器查询 Utilities#

v4 原生支持 Container Queries 相关的 utility classes：

1
<!-- 声明容器 -->
2
<div class="@container">
3
  <!-- 容器查询断点 -->
4
  <div class="@sm:grid-cols-2 @lg:grid-cols-3 @xl:grid-cols-4">
5
    <div class="@sm:flex-row flex-col">
6
      自适应容器宽度的布局
7
    </div>
8
  </div>
9
</div>
10

11
<!-- 命名容器 -->
12
<div class="@container/sidebar">
13
  <div class="@sm/sidebar:hidden">
14
    在 sidebar 容器较窄时隐藏
15
  </div>
16
</div>

改进的任意值语法#

1
<!-- v3 语法仍然支持 -->
2
<div class="bg-[#1da1f2]">...</div>
3

4
<!-- v4 新增：CSS 变量简写 -->
5
<div class="bg-(--my-color)">...</div>
6

7
<!-- 等同于 -->
8
<div class="bg-[var(--my-color)]">...</div>

@utility 自定义 Utility#

v4 引入了 @utility 来定义自定义 utility classes，替代了 v3 中的 @layer utilities + 手动类名：

1
/* 定义自定义 utility */
2
@utility content-grid {
3
  display: grid;
4
  grid-template-columns:
5
    [full-start] minmax(1rem, 1fr)
6
    [content-start] minmax(0, 65ch)
7
    [content-end] minmax(1rem, 1fr)
8
    [full-end];
9

10
  & > * {
11
    grid-column: content;
12
  }
13
}
14

15
@utility text-balance {
16
  text-wrap: balance;
17
}
18

19
@utility scrollbar-hidden {
20
  scrollbar-width: none;
21
  &::-webkit-scrollbar {
22
    display: none;
23
  }
24
}
25

26
@utility glass {
27
  background: rgba(255, 255, 255, 0.1);
28
  backdrop-filter: blur(16px);
29
  border: 1px solid rgba(255, 255, 255, 0.2);
30
}

使用：

1
<main class="content-grid">
2
  <h1 class="text-balance">这是一个很长的标题，会自动平衡换行</h1>
3
  <div class="scrollbar-hidden overflow-y-auto h-96">
4
    隐藏滚动条的可滚动区域
5
  </div>
6
  <div class="glass rounded-xl p-6">
7
    毛玻璃效果的卡片
8
  </div>
9
</main>

@variant 自定义变体#

1
/* 自定义变体 */
2
@variant hocus (&:hover, &:focus-visible);
3
@variant group-active (group:active &);
4
@variant scrolled (.scrolled &);
5

6
/* 基于数据属性的变体 */
7
@variant data-loading (&[data-loading="true"]);
8
@variant data-active (&[data-state="active"]);

1
<button class="hocus:bg-blue-600 hocus:scale-105">
2
  hover 或 focus 时变化
3
</button>
4

5
<div class="data-loading:opacity-50 data-loading:pointer-events-none"
6
     data-loading="true">
7
  加载中状态
8
</div>

从 v3 迁移到 v4#

自动迁移工具#

Tailwind 提供了官方迁移工具：

1
npx @tailwindcss/upgrade

它会自动：

更新 package.json 中的依赖
将 tailwind.config.js 转换为 CSS @theme 配置
更新 CSS 导入语法
移除不再需要的 PostCSS 配置
更新已弃用的 class 名称

手动迁移清单#

如果你需要手动迁移，以下是关键变化：

1. 安装新版本#

1
# 移除旧依赖
2
npm uninstall tailwindcss postcss autoprefixer
3

4
# 安装 v4
5
npm install tailwindcss@4

2. 更新 CSS 入口文件#

1
/* 之前 */
2
@tailwind base;
3
@tailwind components;
4
@tailwind utilities;
5

6
/* 之后 */
7
@import "tailwindcss";

3. 迁移配置#

1
module.exports = {
2
  theme: {
3
    extend: {
4
      colors: {
5
        brand: '#3b82f6',
6
      },
7
      borderRadius: {
8
        '4xl': '2rem',
9
      },
10
    },
11
  },
12
};

1
/* 之后: 在 CSS 中 */
2
@import "tailwindcss";
3

4
@theme {
5
  --color-brand: #3b82f6;
6
  --radius-4xl: 2rem;
7
}

4. 更新构建配置#

Vite：

1
import tailwindcss from '@tailwindcss/vite';
2

3
export default {
4
  plugins: [
5
    tailwindcss(),
6
  ],
7
};

其他构建工具（PostCSS 兼容模式）：

1
export default {
2
  plugins: {
3
    '@tailwindcss/postcss': {},
4
  },
5
};

5. 已弃用/重命名的类#

1
# 一些 v3 中的类在 v4 中重命名
2
 bg-opacity-50  →  bg-black/50 (使用颜色不透明度语法)
3
 text-opacity-75 → text-black/75
4
 decoration-slice → box-decoration-slice
5
 decoration-clone → box-decoration-clone
6
 bg-gradient-to-r → bg-linear-to-r

与构建工具集成#

Vite（推荐）#

v4 对 Vite 有一流支持：

1
import { defineConfig } from 'vite';
2
import tailwindcss from '@tailwindcss/vite';
3

4
export default defineConfig({
5
  plugins: [
6
    tailwindcss(),
7
  ],
8
});

这种方式最快，因为 Tailwind 直接集成到 Vite 的构建管线中，跳过了 PostCSS 层。

CLI 独立使用#

v4 提供了独立的 CLI 工具，不依赖任何构建工具：

1
# 安装
2
npm install tailwindcss @tailwindcss/cli
3

4
# 构建
5
npx @tailwindcss/cli -i src/input.css -o dist/output.css
6

7
# 监听模式
8
npx @tailwindcss/cli -i src/input.css -o dist/output.css --watch
9

10
# 压缩
11
npx @tailwindcss/cli -i src/input.css -o dist/output.css --minify

Astro#

1
import { defineConfig } from 'astro/config';
2
import tailwindcss from '@tailwindcss/vite';
3

4
export default defineConfig({
5
  vite: {
6
    plugins: [tailwindcss()],
7
  },
8
});

性能对比深度分析#

构建性能#

以一个包含 500+ 组件的大型 Vue 项目为例：

1
v3 全量构建:
2
  解析配置: 15ms
3
  扫描内容: 120ms
4
  生成 CSS: 650ms
5
  PostCSS 处理: 80ms
6
  Autoprefixer: 45ms
7
  总计: ~910ms
8

9
v4 全量构建:
10
  Oxide 引擎处理: 85ms
11
  Lightning CSS: 12ms
12
  总计: ~97ms

运行时性能#

v4 生成的 CSS 更高效：

1
/* v3 可能生成冗余的 CSS 变量层 */
2
.bg-blue-500 {
3
  --tw-bg-opacity: 1;
4
  background-color: rgb(59 130 246 / var(--tw-bg-opacity));
5
}
6

7
/* v4 更直接 */
8
.bg-blue-500 {
9
  background-color: #3b82f6;
10
}
11

12
/* 当使用不透明度时才引入变量 */
13
.bg-blue-500\/50 {
14
  background-color: rgb(59 130 246 / 0.5);
15
}

产出文件大小#

场景	v3 (gzip)	v4 (gzip)
小型项目	~8KB	~6KB
中型项目	~15KB	~11KB
大型项目	~25KB	~18KB

v4 产出更小主要得益于 Lightning CSS 的优化压缩和更少的运行时辅助变量。

最佳实践#

1. 拥抱 CSS-first 配置#

1
/* ✅ 在 CSS 中定义设计令牌 */
2
@theme {
3
  --color-brand: oklch(0.65 0.24 265);
4
  --font-display: "Cal Sans", sans-serif;
5
}
6

7
/* ❌ 不要试图保留 JS 配置文件 */

2. 利用原生 CSS 特性#

v4 鼓励使用现代 CSS 特性：

1
/* 使用 CSS 嵌套（Tailwind 原生支持） */
2
.card {
3
  @apply rounded-xl bg-white shadow-soft;
4

5
  &:hover {
6
    @apply shadow-medium;
7
  }
8

9
  & .title {
10
    @apply text-heading font-bold;
11
  }
12
}
13

14
/* 使用 oklch 色彩空间 */
15
@theme {
16
  --color-brand: oklch(0.65 0.24 265);
17
  --color-brand-light: oklch(0.85 0.12 265);
18
  --color-brand-dark: oklch(0.45 0.24 265);
19
}

3. 组件提取策略#

1
/* 使用 @utility 创建可复用的模式 */
2
@utility btn {
3
  display: inline-flex;
4
  align-items: center;
5
  justify-content: center;
6
  padding: var(--spacing-sm) var(--spacing-md);
7
  border-radius: var(--radius-button);
8
  font-weight: 600;
9
  transition: all 0.15s ease;
10
  cursor: pointer;
11
}
12

13
@utility btn-primary {
14
  @apply btn;
15
  background: var(--color-primary);
16
  color: white;
17

18
  &:hover {
19
    filter: brightness(1.1);
20
  }
21
}

4. 性能优化#

1
/* 限制扫描范围 */
2
@source "./src/components/**/*.vue";
3
@source "./src/pages/**/*.astro";
4

5
/* 排除不需要扫描的目录 */
6
@source not "./src/**/*.test.ts";
7
@source not "./src/**/*.spec.ts";

总结#

Tailwind CSS v4 是一次大胆的重写，它带来了：

10-40x 的性能提升：Rust 引擎 + Lightning CSS 让构建飞快
零配置体验：自动内容检测，无需手动指定扫描路径
CSS-first 配置：@theme 替代 JS 配置文件，更直觉
更少的依赖：不再需要 PostCSS、Autoprefixer、cssnano
更小的产出：Lightning CSS 的优化让 CSS 文件更精简
现代 CSS 拥抱：原生嵌套、oklch、Container Queries 等

如果你正在启动新项目，v4 是不二之选。如果是已有项目，官方迁移工具可以帮你平滑过渡。

Tailwind CSS v4 不仅仅是一个 CSS 框架的更新——它代表了前端工具链从 JavaScript 向 Rust 迁移的大趋势，也展示了 CSS-first 开发体验的未来方向。

音乐

音乐