l-blog

主题模式

Tailwind CSS v4 深度解析：CSS-first 的全新时代 ​

Tailwind CSS v4 是一次彻底的重写。抛弃了 JavaScript 配置文件，改用原生 CSS；引入了全新的高性能引擎 Oxide；构建速度提升 5 倍以上。如果你还停留在 v3，这篇文章告诉你为什么值得升级。

v4 最大的变化：告别 tailwind.config.js ​

v3 的配置方式：

javascript
// tailwind.config.js（v3）
module.exports = {
  content: ["./src/**/*.{html,js,ts,jsx,tsx}"],
  theme: {
    extend: {
      colors: {
        brand: {
          50: "#eff6ff",
          500: "#3b82f6",
          900: "#1e3a8a",
        },
      },
      fontFamily: {
        sans: ["Inter", "sans-serif"],
      },
      borderRadius: {
        "4xl": "2rem",
      },
    },
  },
  plugins: [require("@tailwindcss/typography")],
};

v4 的配置方式——纯 CSS：

css
/* app.css（v4）*/
@import "tailwindcss";

@theme {
  --color-brand-50: #eff6ff;
  --color-brand-500: #3b82f6;
  --color-brand-900: #1e3a8a;

  --font-family-sans: "Inter", sans-serif;

  --radius-4xl: 2rem;
}

这不只是语法变化——这意味着你的设计 token 就是原生 CSS 变量，可以在任何地方使用，包括 JavaScript。

安装与配置 ​

bash
# Vite 项目
npm install tailwindcss @tailwindcss/vite
typescript
// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

export default defineConfig({
  plugins: [tailwindcss()],
});
css
/* src/app.css */
@import "tailwindcss";

就这些！v4 不再需要 tailwind.config.js，不再需要 postcss.config.js，不再需要手动配置 content——它会自动扫描项目文件。

Next.js 配置 ​

bash
npm install tailwindcss @tailwindcss/postcss postcss
javascript
// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};
css
/* app/globals.css */
@import "tailwindcss";

@theme：设计系统的核心 ​

@theme 是 v4 最重要的新特性，用 CSS 变量定义你的设计 token：

css
@import "tailwindcss";

@theme {
  /* 颜色系统 */
  --color-primary: oklch(55% 0.2 250);
  --color-primary-light: oklch(70% 0.15 250);
  --color-primary-dark: oklch(40% 0.25 250);

  --color-gray-50: #f9fafb;
  --color-gray-100: #f3f4f6;
  --color-gray-900: #111827;

  /* 字体 */
  --font-sans: "Inter Variable", ui-sans-serif, system-ui;
  --font-mono: "JetBrains Mono", ui-monospace;

  /* 字号 */
  --text-xs: 0.75rem;
  --text-sm: 0.875rem;
  --text-base: 1rem;
  --text-lg: 1.125rem;
  --text-xl: 1.25rem;
  --text-2xl: 1.5rem;

  /* 间距 */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;

  /* 圆角 */
  --radius-4xl: 2rem;
  --radius-5xl: 2.5rem;

  /* 阴影 */
  --shadow-soft: 0 2px 15px -3px rgb(0 0 0 / 0.07);

  /* 动画 */
  --animate-fade-in: fade-in 0.3s ease-out;
  --animate-slide-up: slide-up 0.4s cubic-bezier(0.16, 1, 0.3, 1);
}

/* 配合 @keyframes */
@keyframes fade-in {
  from { opacity: 0; }
  to { opacity: 1; }
}

@keyframes slide-up {
  from { transform: translateY(10px); opacity: 0; }
  to { transform: translateY(0); opacity: 1; }
}

定义后，这些 token 自动生成对应的工具类：

html
<!-- 颜色 -->
<div class="bg-primary text-primary-dark">...</div>

<!-- 字体 -->
<p class="font-sans text-lg">...</p>

<!-- 间距 -->
<div class="p-18 mt-88">...</div>

<!-- 圆角 -->
<div class="rounded-4xl">...</div>

<!-- 动画 -->
<div class="animate-fade-in">...</div>

同时，这些 token 也是原生 CSS 变量，可以在任何地方使用：

css
.custom-component {
  background: var(--color-primary);
  font-family: var(--font-sans);
  border-radius: var(--radius-4xl);
}
javascript
// 在 JS 中读取
const primary = getComputedStyle(document.documentElement)
  .getPropertyValue("--color-primary");

新增工具类 ​

动态间距值 ​

v4 支持任意间距值，无需方括号：

html
<!-- v3：需要方括号 -->
<div class="mt-[13px] p-[7px]">...</div>

<!-- v4：直接写（基于 spacing scale）-->
<div class="mt-13 p-7">...</div>

新的尺寸工具 ​

html
<!-- size-* 同时设置 width 和 height -->
<div class="size-10">...</div>   <!-- w-10 h-10 -->
<div class="size-full">...</div> <!-- w-full h-full -->

<!-- 3D 变换 -->
<div class="rotate-x-45 rotate-y-30 perspective-500">...</div>

<!-- 渐变方向 -->
<div class="bg-linear-to-br from-blue-500 to-purple-600">...</div>
<div class="bg-radial from-white to-gray-900">...</div>
<div class="bg-conic from-red-500 via-yellow-500 to-green-500">...</div>

容器查询（内置） ​

v4 内置了容器查询，不再需要插件：

html
<!-- 定义容器 -->
<div class="@container">
  <!-- 容器宽度 >= 768px 时生效 -->
  <div class="@md:grid @md:grid-cols-2">
    <div>Item 1</div>
    <div>Item 2</div>
  </div>
</div>

<!-- 命名容器 -->
<div class="@container/sidebar">
  <nav class="@lg/sidebar:flex @lg/sidebar:flex-col">...</nav>
</div>

新的变体 ​

html
<!-- 起始/结束（逻辑属性，支持 RTL）-->
<div class="ms-4 me-4 ps-6 pe-6">...</div>
<div class="rounded-s-lg rounded-e-lg">...</div>

<!-- not 变体 -->
<button class="not-disabled:hover:bg-blue-600 disabled:opacity-50">...</button>

<!-- in 变体（父元素状态） -->
<div class="group">
  <span class="in-[.group:hover]:text-blue-500">...</span>
</div>

<!-- nth 变体 -->
<li class="nth-[2n+1]:bg-gray-100">...</li>
<li class="nth-last-2:font-bold">...</li>

<!-- starting 变体（CSS @starting-style）-->
<div class="transition-opacity starting:opacity-0 opacity-100">...</div>

CSS 层叠层（@layer） ​

v4 明确使用 CSS @layer 管理样式优先级：

css
@import "tailwindcss";

/* 在 base 层添加全局样式 */
@layer base {
  h1 {
    @apply text-3xl font-bold tracking-tight;
  }

  a {
    @apply text-primary underline-offset-4 hover:underline;
  }

  * {
    @apply border-border;
  }
}

/* 在 components 层添加组件样式 */
@layer components {
  .btn {
    @apply inline-flex items-center justify-center rounded-lg px-4 py-2
           text-sm font-medium transition-colors focus-visible:outline-none
           focus-visible:ring-2 disabled:pointer-events-none disabled:opacity-50;
  }

  .btn-primary {
    @apply btn bg-primary text-white hover:bg-primary-dark;
  }

  .btn-outline {
    @apply btn border border-gray-300 bg-transparent hover:bg-gray-50;
  }

  .card {
    @apply rounded-xl border border-gray-200 bg-white shadow-soft p-6;
  }
}

/* 在 utilities 层添加自定义工具类 */
@layer utilities {
  .text-balance {
    text-wrap: balance;
  }

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

暗色模式 ​

css
@import "tailwindcss";

@theme {
  --color-bg: #ffffff;
  --color-text: #111827;
  --color-border: #e5e7eb;
}

/* 暗色模式覆盖 */
@media (prefers-color-scheme: dark) {
  :root {
    --color-bg: #0f172a;
    --color-text: #f1f5f9;
    --color-border: #1e293b;
  }
}

/* 或者手动切换（class 模式）*/
.dark {
  --color-bg: #0f172a;
  --color-text: #f1f5f9;
}
html
<!-- 使用 -->
<div class="bg-bg text-text border-border">
  <p class="dark:text-gray-300">自动适配暗色模式</p>
</div>

与 shadcn/ui 集成 ​

shadcn/ui 已全面支持 Tailwind v4：

bash
npx shadcn@latest init
css
/* app/globals.css（shadcn/ui v4 风格）*/
@import "tailwindcss";

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  --color-secondary: var(--secondary);
  --color-muted: var(--muted);
  --color-muted-foreground: var(--muted-foreground);
  --color-border: var(--border);
  --color-ring: var(--ring);
  --radius-lg: var(--radius);
  --radius-md: calc(var(--radius) - 2px);
  --radius-sm: calc(var(--radius) - 4px);
}

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --secondary: oklch(0.97 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  --border: oklch(0.922 0 0);
  --ring: oklch(0.708 0 0);
  --radius: 0.625rem;
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.985 0 0);
  --border: oklch(1 0 0 / 10%);
}

v3 → v4 迁移 ​

bash
# 官方迁移工具（自动处理大部分变化）
npx @tailwindcss/upgrade

主要变化速查：

v3v4
tailwind.config.js@theme {} in CSS
content: [...]自动扫描
bg-opacity-50bg-black/50
text-opacity-75text-black/75
flex-shrink-0shrink-0
overflow-ellipsistext-ellipsis
decoration-slicebox-decoration-slice
shadow-smshadow-xs
ring-offset-*原生 outline-offset-*
@tailwindcss/typography内置 prose
@tailwindcss/forms内置表单重置
@tailwindcss/container-queries内置 @container

性能对比 ​

bash
# 构建速度测试（中型项目，~500 个组件文件）

Tailwind CSS v3 (PostCSS)  : ~1200ms 全量构建
Tailwind CSS v4 (Oxide)    :  ~180ms 全量构建   快 6.7 倍
Tailwind CSS v4 增量构建    :   ~15ms            快 80 倍

v4 的 Oxide 引擎用 Rust 编写，扫描文件和生成 CSS 的速度有质的飞跃。

总结 ​

Tailwind CSS v4 的核心变化：

特性价值
CSS-first 配置设计 token 即 CSS 变量，全局可用
Oxide 引擎Rust 驱动，构建速度提升 5-80 倍
零配置自动扫描，无需 content 配置
内置容器查询不再需要插件
原生 CSS 层叠@layer 管理优先级更清晰
更多工具类size-*、3D 变换、新渐变、逻辑属性

如果你的项目用 Vite 或 Next.js，现在就可以升级——迁移工具会帮你处理大部分变化，而你得到的是更快的构建速度和更强大的设计系统能力。

本文由小虾子 撰写

Last updated: