tailwindcss-fundamentals-v4

Tailwind CSS v4 基础知识（2025/2026）

概述

Tailwind CSS v4.0 于 2025 年 1 月 22 日发布，进行了彻底重写，采用基于 Rust 的引擎、CSS 优先的配置方式，并显著提升了性能。

相较于 v3 的主要变化

特性	v3	v4
配置	JavaScript（tailwind.config.js）	CSS 优先（@theme 指令）
引擎	Node.js	Rust（速度快 10 倍）
颜色格式	hex/rgb	OKLCH（感知均匀）
插件	JS 文件	@plugin 指令
自定义工具类	JS 配置	@utility 指令
PostCSS 导入	postcss-import	内置
Autoprefixer	必需	内置
CSS 嵌套	postcss-nested	内置
内容检测	显式配置	自动

安装

Vite 项目（推荐）

npm install -D tailwindcss @tailwindcss/vite

// vite.config.js
import tailwindcss from '@tailwindcss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [tailwindcss()]
})

PostCSS 项目

npm install -D tailwindcss @tailwindcss/postcss

// postcss.config.mjs
export default {
  plugins: {
    '@tailwindcss/postcss': {}
  }
}

CSS 入口点

/* app.css - The only required CSS file */
@import "tailwindcss";

CSS 优先的配置

@theme 指令

使用基于 CSS 的配置替代 tailwind.config.js：

@import "tailwindcss";

@theme {
  /* Colors using modern oklch */
  --color-primary: oklch(0.6 0.2 250);
  --color-secondary: oklch(0.7 0.15 180);
  --color-accent: oklch(0.8 0.2 30);

  /* Typography */
  --font-display: "Satoshi", sans-serif;
  --font-body: "Inter", sans-serif;

  /* Custom spacing */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 2rem;
  --spacing-xl: 4rem;

  /* Custom breakpoints */
  --breakpoint-xs: 475px;
  --breakpoint-3xl: 1920px;
}

主题变量参考

类别	变量模式	示例
颜色	--color-*	--color-brand-500
字体	--font-*	--font-heading
间距	--spacing-*	--spacing-4
断点	--breakpoint-*	--breakpoint-3xl
圆角	--radius-*	--radius-lg
阴影	--shadow-*	--shadow-xl
动画	--animate-*	--animate-fade-in
缓动	--ease-*	--ease-bounce

禁用默认值

@theme {
  /* Start fresh - disable all default theme values */
  --*: initial;

  /* Define only what you need */
  --spacing: 4px;
  --font-body: Inter, sans-serif;
  --color-primary: oklch(0.72 0.11 221.19);
  --color-secondary: oklch(0.74 0.17 40.24);
}

自定义工具类

静态工具类

/* Define custom utility in CSS */
@utility content-auto {
  content-visibility: auto;
}

@utility text-balance {
  text-wrap: balance;
}

@utility scrollbar-hide {
  -ms-overflow-style: none;
  scrollbar-width: none;
}

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

用法：

<div class="content-auto scrollbar-hide">
  <h1 class="text-balance">Long headline that should balance nicely</h1>
</div>

函数式工具类

/* Utility that accepts values */
@utility tab-* {
  tab-size: --value(integer);
}

@utility text-shadow-* {
  text-shadow: 0 0 --value([length]) currentColor;
}

/* With theme reference */
@utility gap-safe-* {
  gap: max(--value(--spacing-*), env(safe-area-inset-bottom));
}

用法：

<pre class="tab-4">Code with 4-space tabs</pre>
<h1 class="text-shadow-[2px]">Glowing text</h1>
<div class="gap-safe-4">Safe area aware gap</div>

自定义变体

@custom-variant 指令

/* Dark mode with selector */
@custom-variant dark (&:where(.dark, .dark *));

/* Custom state variants */
@custom-variant hocus (&:hover, &:focus);
@custom-variant group-hocus (:merge(.group):hover &, :merge(.group):focus &);

/* Data attribute variants */
@custom-variant data-loading (&[data-loading="true"]);
@custom-variant data-active (&[data-state="active"]);

/* Child selectors */
@custom-variant children (& > *);
@custom-variant not-first (& > *:not(:first-child));

用法：

<button class="hocus:bg-blue-600">Hover or focus</button>
<div class="data-loading:opacity-50" data-loading="true">Loading...</div>
<ul class="children:border-b not-first:pt-2">
  <li>Item 1</li>
  <li>Item 2</li>
</ul>

加载插件

@plugin 指令

@import "tailwindcss";

/* Load official plugins */
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
@plugin "@tailwindcss/container-queries";

/* Load local plugin */
@plugin "./my-plugin.js";

带选项的插件

@plugin "@tailwindcss/typography" {
  className: wysiwyg;
}

@plugin "@tailwindcss/forms" {
  strategy: class;
}

使用前缀

@import "tailwindcss" prefix(tw);

@theme {
  /* Define without prefix */
  --font-display: "Satoshi", sans-serif;
}

<div class="tw:flex tw:bg-red-500 tw:hover:bg-red-600">
  Content
</div>

生成的 CSS 变量包含前缀：

:root {
  --tw-font-display: "Satoshi", sans-serif;
}

在代码中使用 CSS 变量

用 var() 替代 theme()

/* v3 approach (deprecated) */
.old-way {
  background-color: theme(colors.red.500);
}

/* v4 approach */
.new-way {
  background-color: var(--color-red-500);
}

/* In media queries, use CSS variable names */
@media (width >= theme(--breakpoint-xl)) {
  /* styles */
}

核心工具类类别

布局

<div class="flex flex-col md:flex-row items-center justify-between gap-4">


<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">


<div class="container mx-auto px-4">

间距

<div class="p-4 px-6 py-2">


<div class="m-4 mx-auto my-8">


<div class="gap-4 gap-x-6 gap-y-2">

排版

<p class="text-sm md:text-base lg:text-lg">


<h1 class="font-bold">


<p class="text-gray-600 dark:text-gray-300">


<p class="leading-relaxed">

颜色

<div class="bg-white dark:bg-gray-900">


<p class="text-blue-600">


<div class="border border-gray-200">


<button class="focus:ring-2 focus:ring-blue-500">

尺寸

<div class="w-full md:w-1/2 lg:w-1/3">


<div class="h-screen min-h-[500px]">


<div class="max-w-xl mx-auto">

任意值

<div class="top-[117px] left-[calc(50%-4rem)]">


<div class="bg-[var(--my-color)]">


<div class="grid-cols-[1fr_500px_2fr]">

important 修饰符

<div class="!mt-0">


<div class="hover:!bg-red-500">

内置功能（无需配置）

功能	v3 要求	v4
@import 处理	postcss-import	内置
厂商前缀	autoprefixer	内置
CSS 嵌套	postcss-nested	内置
内容检测	content 配置	自动

图层

/* Use native CSS layers */
@layer base {
  h1 {
    @apply text-2xl font-bold;
  }
}

@layer components {
  .btn {
    @apply px-4 py-2 rounded font-medium;
  }
}

@layer utilities {
  /* Custom utilities via @utility directive instead */
}

最佳实践（2025/2026）

1. 在设计系统中使用 OKLCH 颜色

OKLCH 可提供感知均匀的颜色、更好的渐变效果，并支持广色域：

@theme {
  /* OKLCH format: oklch(lightness chroma hue) */
  /* Lightness: 0-1, Chroma: 0-0.4, Hue: 0-360 */

  /* Primary palette - adjust L for shades */
  --color-primary-50: oklch(0.97 0.02 250);
  --color-primary-100: oklch(0.93 0.04 250);
  --color-primary-500: oklch(0.55 0.2 250);  /* Base */
  --color-primary-600: oklch(0.48 0.2 250);
  --color-primary-900: oklch(0.27 0.12 250);

  /* Semantic colors */
  --color-success: oklch(0.6 0.15 145);
  --color-warning: oklch(0.75 0.15 65);
  --color-error: oklch(0.55 0.2 25);
}

2. 实现流式排版

平滑缩放，不会因断点而跳变：

@theme {
  /* Fluid type scale using clamp() */
  /* clamp(min, preferred, max) */
  --text-fluid-xs: clamp(0.75rem, 0.7rem + 0.25vw, 0.875rem);
  --text-fluid-sm: clamp(0.875rem, 0.8rem + 0.375vw, 1rem);
  --text-fluid-base: clamp(1rem, 0.9rem + 0.5vw, 1.125rem);
  --text-fluid-lg: clamp(1.125rem, 1rem + 0.625vw, 1.25rem);
  --text-fluid-xl: clamp(1.25rem, 1rem + 1.25vw, 1.5rem);
  --text-fluid-2xl: clamp(1.5rem, 1.1rem + 2vw, 2rem);
  --text-fluid-3xl: clamp(1.875rem, 1.2rem + 3.375vw, 2.5rem);
  --text-fluid-4xl: clamp(2.25rem, 1rem + 6.25vw, 3.5rem);
}

重要：始终将 vw 与 rem 结合使用，以确保可访问性（支持缩放）。

3. 流式间距系统

@theme {
  /* Fluid spacing that scales with viewport */
  --spacing-fluid-sm: clamp(0.5rem, 0.4rem + 0.5vw, 1rem);
  --spacing-fluid-md: clamp(1rem, 0.75rem + 1.25vw, 2rem);
  --spacing-fluid-lg: clamp(2rem, 1rem + 3vw, 4rem);
  --spacing-fluid-section: clamp(4rem, 2rem + 8vw, 8rem);
}

4. 按类别组织主题

@theme {
  /* === Colors === */
  --color-primary: oklch(0.6 0.2 250);
  --color-secondary: oklch(0.7 0.15 180);
  --color-success: oklch(0.6 0.15 145);
  --color-error: oklch(0.55 0.2 25);

  /* === Typography === */
  --font-sans: 'Inter Variable', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', ui-monospace, monospace;

  /* === Fluid Typography === */
  --text-fluid-base: clamp(1rem, 0.9rem + 0.5vw, 1.25rem);
  --text-fluid-lg: clamp(1.25rem, 1rem + 1.25vw, 2rem);

  /* === Spacing === */
  --spacing-page: 2rem;
  --spacing-fluid-section: clamp(4rem, 2rem + 8vw, 8rem);

  /* === Border Radius === */
  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 0.75rem;

  /* === Shadows === */
  --shadow-sm: 0 1px 2px oklch(0 0 0 / 0.05);
  --shadow-md: 0 4px 6px oklch(0 0 0 / 0.07);

  /* === Easing === */
  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
  --ease-snappy: cubic-bezier(0.2, 0, 0, 1);
}

5. 保持 @utility 定义简单

/* Good - single purpose utilities */
@utility truncate-2 {
  display: -webkit-box;
  -webkit-line-clamp: 2;
  -webkit-box-orient: vertical;
  overflow: hidden;
}

@utility text-balance {
  text-wrap: balance;
}

@utility content-auto {
  content-visibility: auto;
  contain-intrinsic-size: auto 500px;
}

/* Safe area utilities for notched devices */
@utility safe-area-pb {
  padding-bottom: env(safe-area-inset-bottom);
}

@utility safe-area-pt {
  padding-top: env(safe-area-inset-top);
}

/* Avoid - too complex, use components instead */
@utility card-fancy {
  /* Too many properties - use @layer components */
}

6. 移动优先的类排序

始终按渐进方式组织响应式类：

<div class="
  text-sm md:text-base lg:text-lg
  p-4 md:p-6 lg:p-8
  grid-cols-1 md:grid-cols-2 lg:grid-cols-3
">
  Content
</div>

7. 可访问的交互元素

<button class="
  min-h-11 min-w-11 px-4 py-2.5
  bg-primary-600 hover:bg-primary-700 text-white
  rounded-lg font-medium
  focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500 focus-visible:ring-offset-2
  transition-colors motion-reduce:transition-none
">
  Button Text
</button>

常见迁移问题

边框颜色默认值

/* v3: border used gray-200 by default */
/* v4: border uses currentColor */

/* Fix: explicitly set color */
@theme {
  --default-border-color: var(--color-gray-200);
}

Ring 默认值

/* v3: ring was 3px blue-500 */
/* v4: ring is 1px currentColor */

/* Fix: restore v3 behavior */
@theme {
  --default-ring-width: 3px;
  --default-ring-color: var(--color-blue-500);
}

按钮光标

/* v4: buttons use cursor: default */
/* Fix: add pointer globally if needed */
button {
  cursor: pointer;
}