朝花夕拾
RSS 订阅
教程·阅读约 5 分钟·
Tailwind CSS v4 完全入门指南：CSS 优先配置、性能飞跃与新特性实战

Tailwind CSS v4 完全入门指南：CSS 优先配置、性能飞跃与新特性实战

从安装到实战，全面解析 Tailwind CSS v4 的 CSS-first 配置、Oxide 引擎、容器查询内建支持等核心变化，附完整迁移指南

原创。手把手教你从零上手 Tailwind CSS v4。读完本文你将掌握：新引擎的安装配置、CSS-first 主题系统、自定义工具类的创建方法、容器查询和渐变等内建新特性，以及从 v3 迁移的完整步骤。

前言：为什么 Tailwind CSS v4 值得重学一遍？

2025 年 1 月，Adam Wathan 正式发布了 Tailwind CSS v4.0。这不是一个渐进式的小版本更新——整个框架从底层到 API 完全重写了一遍。

最大的变化是：你不再需要 tailwind.config.js 了。所有配置都写在 CSS 里。同时，构建性能提升了 3-4 倍，增量构建甚至快了 180 多倍。

对开发者来说，这意味着更少的配置文件、更快的开发反馈、以及更自然地利用现代 CSS 能力。但这也意味着 v3 时代积累的很多配置习惯要改。

本文从零开始，带你完整走一遍 v4 的学习路径。

本文内容基于 Tailwind CSS 官方文档（tailwindcss.com/blog/tailwindcss-v4）和实际开发实践编写。

—— 广告 ——

一、安装与配置：前所未有的简单

1.1 使用 PostCSS（通用方案）

code
npm install tailwindcss @tailwindcss/postcss

然后在 postcss.config.js 中添加插件：

code
module.exports = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

最后在 CSS 入口文件中写一行：

code
@import "tailwindcss";

就这样。不需要 @tailwind base、@tailwind components、@tailwind utilities 那些指令了。不需要配置 content 数组——引擎会自动扫描你的项目文件。

1.2 使用 Vite 插件（推荐，性能更好）

code
npm install tailwindcss @tailwindcss/vite
code
// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";
 
export default defineConfig({
  plugins: [tailwindcss()],
});

Vite 插件比 PostCSS 方案性能更好，因为它和 Vite 的 HMR 深度集成。如果你的项目用 Vite（无论是 React、Vue 还是 Svelte），优先选这个方案。

1.3 安装验证

在 CSS 中写入 @import "tailwindcss" 后，在 HTML 里试一个：

code
<div class="bg-blue-500 text-white p-4 rounded-lg">
  Hello Tailwind v4!
</div>

如果能正常渲染蓝色背景和白字，就是正确的。

二、CSS 优先配置：告别 tailwind.config.js

这是 v4 最具颠覆性的变化。

2.1 @theme 指令

在 v3 里，你要在 tailwind.config.js 里写：

code
module.exports = {
  theme: {
    extend: {
      colors: {
        avocado: {
          100: "#e6f7e6",
          500: "#84cc16",
        },
      },
    },
  },
};

在 v4 里，所有主题配置搬到 CSS 中，用 @theme 指令：

code
@import "tailwindcss";
 
@theme {
  --color-avocado-100: oklch(0.99 0 0);
  --color-avocado-500: oklch(0.84 0.18 117.33);
  --font-display: "Satoshi", "sans-serif";
  --breakpoint-3xl: 120rem;
}

定义之后，bg-avocado-500、text-avocado-100、font-display 等工具类自动生效。

关键优势：每个 --color-* 变量都会自动生成对应的 CSS 自定义属性在 :root 上，所以你可以在任意 CSS 中引用它们：

code
.card {
  background: var(--color-avocado-100);
}

2.2 覆盖和禁用默认主题

如果你不想用 Tailwind 自带的默认颜色，可以彻底禁用：

code
@theme {
  --color-*: initial;
}

或者只覆盖部分命名空间：

code
@theme {
  --font-*: initial;
  --font-display: "Inter", sans-serif;
  --font-mono: "JetBrains Mono", monospace;
}

2.3 带副属性的自定义工具

在 v4 中，你可以在 @theme 中定义带多个属性的复合工具类：

code
@theme {
  --text-logo: 1.5rem;
  --text-logo--font-weight: 700;
  --text-big: 4rem;
  --text-big--font-weight: 800;
  --text-big--line-height: 1.1;
}

这样 text-logo 和 text-big 会自动应用所有定义好的属性，减少 HTML 中的类名数量。

三、自定义工具类与状态变体

3.1 @utility 指令

如果要创建完全自定义的单一工具类，用 @utility：

code
@utility glass {
  background: rgba(255, 255, 255, 0.1);
  backdrop-filter: blur(12px);
  border: 1px solid rgba(255, 255, 255, 0.2);
}
 
@utility text-balance {
  text-wrap: balance;
}

然后在 HTML 里直接用：

code
<div class="glass text-balance">毛玻璃效果卡片</div>

3.2 @variant 指令

自定义状态变体也有了全新语法。比如要同时匹配 hover 和 focus：

code
@variant hocus (&:hover, &:focus);
code
<button class="bg-blue-500 hocus:bg-blue-600">悬停或聚焦时变色</button>

对于复杂的组合条件：

code
@variant pointer-coarse {
  @media (pointer: coarse) {
    @variant hover {
      &:hover {
        @slot;
      }
    }
  }
}

3.3 自定义数据属性变体

v4 支持通过 data- 变体直接匹配自定义布尔属性：

code
<div data-current class="data-current:opacity-100 opacity-50">
  只有当 data-current 存在时才会完全不透明
</div>

四、性能飞跃：Oxide 引擎

v4 的核心是一个全新引擎（内部代号 Oxide），用 Rust 重写了 CSS 生成逻辑。官方给出的基准测试非常惊人：

场景v3.4v4.0提升
完整构建378ms100ms3.78x
增量构建（新 CSS）44ms5ms8.8x
增量构建（无新 CSS）35ms192µs182x

这个性能提升不是靠缓存实现的——它来自引擎架构的全面优化。在实际开发中，最直接的感受就是热更新几乎瞬间完成，再也不用看着终端旋转等待了。

引擎内部还集成了 Lightning CSS，自动处理 CSS 前缀、代码压缩和 @import 合并，所以你可以移除项目中独立的 postcss-import 和 autoprefixer 依赖。

五、内建新特性

5.1 容器查询（Container Queries）

v3 时代需要安装 @tailwindcss/container-queries 插件。v4 直接内建支持。

在父元素上标记容器：

code
<div class="@container">
  <div class="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-4">
    <!-- 容器宽度 sm 时 2 列，lg 时 4 列 -->
  </div>
</div>

新增的 @max-* 变体支持最大宽度限制，组合使用可以实现精确的范围控制：

code
<div class="flex @min-md:@max-xl:hidden">
  <!-- 容器宽度在 md 和 xl 之间时隐藏 -->
</div>

5.2 动态度量间距

v4 的间距体系从固定的 1:2 比例改成了基于 --spacing 变量的动态计算：

code
:root {
  --spacing: 0.25rem; /* 基础单位 */
}

所有间距类（p-*、m-*、w-*、h-*、gap-* 等）的计算公式都是 calc(var(--spacing) * N)。

这意味着 p-21 不再是未定义的值——它会自动变为 0.25rem × 21 = 5.25rem。不需要写 p-[5.25rem] 了。

如果你要限制间距范围：

code
@theme {
  --spacing: initial;
  --spacing-1: 0.25rem;
  --spacing-2: 0.5rem;
  --spacing-4: 1rem;
  --spacing-8: 2rem;
}

5.3 色彩系统升级：Oklch + P3 色域

v4 的默认调色板从 rgb 升级到了 oklch 色彩空间，支持 P3 宽色域。颜色更鲜艳，还解决了长期以来色彩明度不统一的问题。

code
/* 在 CSS 中直接使用 oklch 定义主题色 */
@theme {
  --color-primary: oklch(0.6 0.2 260);
  --color-secondary: oklch(0.7 0.15 30);
}

同时，不透明度控制改用 CSS 的 color-mix() 函数，完全解决了之前 bg-black/50 无法用于渐变的痛点。

5.4 全新渐变能力

v4 添加了大量渐变工具类：

code
<div class="bg-linear-to-r from-cyan-500 to-blue-500">
  <!-- 线性渐变 -->
</div>
<div class="bg-radial from-purple-500 to-pink-500">
  <!-- 径向渐变 -->
</div>
<div class="bg-conic from-yellow-500 via-red-500 to-purple-500">
  <!-- 锥形渐变 -->
</div>

bg-linear-to-* 取代了 v3 的 bg-gradient-to-*。新方案支持更多渐变类型（linear、radial、conic），并且每个渐变工具类都可以通过 color-mix() 精确控制不透明度。

5.5 逻辑属性支持

v4 全面采用 CSS 逻辑属性，输出更小，RTL 支持更自然：

code
/* v4 输出 */
.mx-4 { margin-inline: calc(var(--spacing) * 4); }
 
/* 等价于 v3 的 */
.mx-4 { margin-left: 1rem; margin-right: 1rem; }

逻辑属性会自动响应 writing-mode 和 direction 的变化，在多语言网站中特别有用。

六、从 v3 迁移到 v4

6.1 使用迁移工具

官方提供了一个自动迁移工具，能完成大部分繁琐工作：

code
npx @tailwindcss/upgrade

它会自动：

  • 将 tailwind.config.js 中的 theme.extend 内容转换为 @theme 指令
  • 替换 @tailwind 指令为 @import "tailwindcss"
  • 将 bg-gradient-to-* 替换为 bg-linear-to-*
  • 简化旧版任意值语法

6.2 手动迁移要点

如果不想用迁移工具，或者迁移后需要手动调整，关注以下几点：

  1. 移除 tailwind.config.js，将配置迁移到 CSS 的 @theme 块中
  2. 替换配置文件中的 @tailwind base/components/utilities 为 @import "tailwindcss"
  3. 检查渐变类名：bg-gradient-to-r → bg-linear-to-r
  4. 移除 @tailwindcss/container-queries 依赖——已内建
  5. 移除 postcss-import 和 autoprefixer——已内建
  6. 注意 text-* 类的变化——在 v4 中所有 1-12 号字号的对应值可能变了，需要检查设计稿中的实际 font-size

6.3 兼容方案

如果你有一个大型 v3 项目，不能一次性迁移完成，可以在 v4 中保留旧的配置文件：

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

@config 指令会让 v4 引擎以兼容模式解析 v3 格式的配置文件。但注意：corePlugins、separator、safelist 在 v4 中不支持。

七、实战：创建一张毛玻璃风格的导航卡片

最后，我们来做一个完整的实战示例：一张使用 v4 新特性的导航卡片。

code
/* styles.css */
@import "tailwindcss";
 
@theme {
  --color-deep-purple: #414387;
  --color-lavender: #eae3f5;
  --color-magenta: #f0456f;
  --font-display: "Inter", sans-serif;
}
 
@utility glass {
  background: rgba(255, 255, 255, 0.08);
  backdrop-filter: blur(16px);
  border: 1px solid rgba(255, 255, 255, 0.15);
}
 
@variant hocus (&:hover, &:focus);
code
<!-- 使用这些工具类 -->
<div class="@container p-4">
  <div class="glass rounded-2xl p-6
              grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-3 gap-4">
    
    <a href="#" class="flex items-center gap-3 p-4 rounded-xl
                       bg-white/5 hocus:bg-white/10
                       transition-colors duration-200">
      <span class="w-10 h-10 rounded-lg bg-linear-to-br from-deep-purple to-lavender"></span>
      <span class="font-display text-white">仪表盘</span>
    </a>
 
    <a href="#" class="flex items-center gap-3 p-4 rounded-xl
                       bg-white/5 hocus:bg-white/10
                       transition-colors duration-200">
      <span class="w-10 h-10 rounded-lg bg-linear-to-br from-magenta to-lavender"></span>
      <span class="font-display text-white">项目</span>
    </a>
 
    <a href="#" class="flex items-center gap-3 p-4 rounded-xl
                       bg-white/5 hocus:bg-white/10
                       transition-colors duration-200
                       @sm:col-span-2 @lg:col-span-1">
      <span class="w-10 h-10 rounded-lg bg-linear-to-br from-purple-500 to-pink-500"></span>
      <span class="font-display text-white">设置</span>
    </a>
  </div>
</div>

这个例子同时用到了 @theme（自定义颜色和字体）、@utility（glass 毛玻璃效果）、@variant（hocus 组合状态）、容器查询（响应式列数）、渐变（图标背景）和逻辑间距——覆盖了 v4 的大部分核心新特性。

八、总结

Tailwind CSS v4 不是一个简单的大版本号增加。它代表了 CSS 工具类框架的一次架构升级：

  • CSS 优先：告别 JS 配置文件，配置回归 CSS
  • 现代 CSS 能力：Oklch 色彩、容器查询、逻辑属性、color-mix() 全部内建
  • 极致性能：Rust 引擎让构建快 3-180 倍
  • 更少的依赖：内置 import 处理、前缀自动添加，移除了一大堆配套插件

如果你还没升级，现在就是最佳时机——v4 已经发布了 18 个月，生态成熟，迁移工具完善，社区中的踩坑记录也已经足够丰富。

Tailwind CSSCSS前端开发VitePostCSS
分享到
微博Twitter

© 2026 四月

原文链接：https://www.aprilzz.com/tutorials/tailwind-v4-complete-guide

相关文章

HTML 中隐藏的宝藏：<dl> 标签完全使用指南

详细介绍 HTML <dl> 描述列表标签的语义、用法和最佳实践，包括多值、分组、无障碍访问等进阶技巧

内网服务 TLS 证书最佳实践：用 Split-Horizon DNS 告别自签名证书

无需自签名证书、无需手动信任每个客户端，通过 Split-Horizon DNS + Let's Encrypt + 反向代理 WAF 实现内网服务的自动化 TLS 方案

PostgreSQL B-Tree 索引深度解析：从原理到 pageinspect 实操

从 B-Tree 数据结构讲起，用 pageinspect 插件直接查看 PostgreSQL 索引的内部结构，理解索引如何工作、如何调优。适合想真正搞懂索引原理的开发者。