Tailwind CSS v4：迁移指南和新功能

Tailwind CSS v4 是该框架推出以来最重要的重写。 JavaScript 配置文件已消失 — 取而代之的是使用自定义属性的 CSS-first 配置。类 API 基本上没有变化，但内部结构是全新的：基于 Rust 的引擎 (oxide)、对 P3 色域的一流支持、本机容器查询以及直接与 CSS 集成而不是通过 PostCSS 插件集成的构建管道。

本指南将引导您了解更改的内容、更改的原因以及如何将实际生产应用程序从 Tailwind v3 迁移到 v4。我们将介绍可能会让您感到困惑的重大变化以及值得立即采用的新功能。

要点

tailwind.config.js 已弃用 — 使用 @theme 指令将配置移至 CSS

导入从 @tailwind base/components/utilities 更改为单个 @import "tailwindcss"

自定义颜色现在使用 --color-* 命名空间下的 CSS 自定义属性

content 配置是自动的 — Tailwind v4 通过 glob 自动扫描文件

容器查询现在内置有 @container 和 @sm:、@lg: 变体

通过 oklch() 颜色空间支持所有内置颜色的 P3 色域

@apply 仍然有效，但对于 CSS 自定义属性来说不太必要

JIT 引擎被 Oxide (Rust) 取代——编译速度显着加快

发生了什么变化以及原因

Tailwind v3 使用 PostCSS 作为处理管道、JavaScript 配置文件，并通过用 JavaScript 编写的 JIT 引擎生成实用程序类。这很有效，但也有局限性：

配置需要 JavaScript，因此无法从纯 CSS 工具访问
自定义属性必须与 Tailwind 配置分开设置
容器查询需要插件
色彩系统不支持P3色域

Tailwind v4 通过将配置移至 CSS 本身、使用浏览器的本机 CSS 自定义属性系统以及用 Rust 重写引擎以将构建速度提高 5-10 倍来解决所有这些问题。

安装

# Tailwind v4
pnpm add tailwindcss@^4.0.0 @tailwindcss/vite

# For Next.js
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

@tailwindcss/vite 插件直接与 Vite 集成。对于 Next.js（内部使用 PostCSS），请使用 @tailwindcss/postcss。

CSS-优先配置

这是最大的观念转变。您的 globals.css 成为 Tailwind 配置的真实来源：

/* Before: globals.css with v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* After: globals.css with v4 */
@import "tailwindcss";

/* Theme configuration replaces tailwind.config.js */
@theme {
  /* Custom colors as CSS custom properties */
  --color-brand-50: oklch(97% 0.02 250);
  --color-brand-100: oklch(94% 0.04 250);
  --color-brand-500: oklch(62% 0.18 250);
  --color-brand-900: oklch(28% 0.09 250);

  /* Custom font families */
  --font-sans: 'Inter', system-ui, sans-serif;
  --font-mono: 'JetBrains Mono', monospace;

  /* Custom spacing */
  --spacing-18: 4.5rem;
  --spacing-88: 22rem;

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

  /* Custom shadows */
  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%), 0 1px 2px oklch(0% 0 0 / 8%);
}

您的 tailwind.config.js 可以被删除（或暂时保留 - v4 在迁移过程中支持这两种方式）。

内容检测

Tailwind v4 自动检测模板文件。你在 v3 中精心维护的 content 配置消失了：

// v3 tailwind.config.js — you needed this
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx}',
  ],
  // ...
}

在 v4 中，Tailwind 使用合理的默认设置自动扫描您的项目。如果您的文件位于不寻常的位置，您可以显式包含它们：

@import "tailwindcss";
@source "../scripts/*.ts"; /* Scan additional paths */
@source "../../packages/ui/src/**/*.tsx"; /* Monorepo workspace packages */

PostCSS 配置更新

对于 Next.js 项目（以及任何基于 PostCSS 的设置），更新您的 PostCSS 配置：

// Before: postcss.config.js with v3
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

// After: postcss.config.mjs with v4
export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

默认情况下，autoprefixer 包含在 @tailwindcss/postcss 中。删除单独的 autoprefixer 依赖项。

颜色系统：OKLCH

Tailwind v4 使用 OKLCH 作为其内置调色板。 OKLCH 是一个感知上均匀的色彩空间 - 与 HSL 不同，调整亮度实际上对人眼来说看起来是等量的步骤。

/* v4 colors use OKLCH internally */
/* bg-blue-500 generates: */
background-color: oklch(62.8% 0.258 264.1);

/* Custom colors with OKLCH */
@theme {
  --color-ecosire-amber: oklch(78% 0.18 80);
  --color-ecosire-navy: oklch(22% 0.04 250);
}

对于更宽色域的显示器（大多数现代手机和 Mac），OKLCH 可实现 sRGB 根本无法表示的颜色。对于不支持 P3 的显示器，oklch() 值会自动转换为 rgb()。

容器查询——内置

容器查询现在在 v4 中是一流的。无需插件：

/* Define a container */
.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

<!-- Responsive based on parent container, not viewport -->
<div class="card-wrapper">
  <div class="@sm:flex-row @lg:grid-cols-3 flex flex-col">
    <!-- Layout changes based on container width, not screen width -->
  </div>
</div>

这实现了组件级响应能力——侧边栏卡和全宽卡可以具有不同的布局，而无需单独的 CSS。

命名容器让您可以定位特定的祖先：

<div class="card-wrapper [container-name:card]">
  <div class="@card/sm:text-lg text-base">
    Responsive to the 'card' container
  </div>
</div>

CSS 自定义属性集成

@theme 中定义的自定义属性可以在任何地方访问 - CSS、JavaScript 和读取 CSS 变量的设计工具：

@theme {
  --color-primary: oklch(62% 0.18 250);
  --spacing-section: 5rem;
}

// Access in JavaScript/TypeScript
const style = getComputedStyle(document.documentElement);
const primary = style.getPropertyValue('--color-primary');

<!-- Use in inline styles -->
<div style={{ color: 'var(--color-primary)' }}>
  Themed content
</div>

这取代了在 tailwind.config.js 和 tokens.ts 文件中维护并行值的模式 - 现在 CSS 中有一个单一的事实来源。

重大变更

1.插件 API 更改

使用 addBase、addComponents、addUtilities 的 v3 插件与 v4 不兼容。使用新的图层系统将它们重写为 CSS：

/* v3 plugin equivalent in v4 CSS */
@layer base {
  h1 {
    @apply text-3xl font-bold;
  }
}

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

2. @apply 与自定义类

具有非 Tailwind 类的 @apply 在 v4 中受到更多限制。仅将 @apply 与实际实用程序类一起使用：

/* This works in v4 */
.btn-primary {
  @apply bg-blue-500 text-white px-4 py-2 rounded-lg;
}

/* This is deprecated — use regular CSS instead */
.btn-primary {
  @apply custom-shadow; /* custom-shadow is not a Tailwind utility */
}

3. tailwind.config.js theme.extend 消失了

JS 中的配置不再是主要路径。在 CSS 中使用 @theme。如果两者都有，则 CSS 配置优先。

4.默认调色板命名

v4 中更改了一些颜色名称。运行官方的 codemod 来捕获它们：

npx @tailwindcss/upgrade@next --config tailwind.config.js

迁移策略

对于大型生产应用程序，增量迁移：

阶段 1：更新安装

pnpm remove tailwindcss autoprefixer postcss
pnpm add tailwindcss@^4.0.0 @tailwindcss/postcss

更新postcss.config.mjs：

export default {
  plugins: { '@tailwindcss/postcss': {} },
};

更新globals.css：

/* Replace the three @tailwind directives */
@import "tailwindcss";

阶段 2：运行 codemod

npx @tailwindcss/upgrade@next

这会自动完成大部分迁移：更新颜色名称、将配置转换为 CSS 以及标记需要手动注意的问题。

阶段 3：将配置移至 CSS

将您的 tailwind.config.js 主题值移至 CSS 中的 @theme 。验证通过后删除配置文件。

第 4 阶段：采用新功能

在适当的情况下，将基于视口的响应断点替换为容器查询。采用 OKLCH 进行自定义颜色以获得 P3 色域支持。

性能改进

Tailwind v4 的 Oxide 引擎 (Rust) 可显着加快构建速度：

	v3（JavaScript JIT）	v4（氧化物、锈）
冷建造	2.1秒	0.3秒
增量构建	120 毫秒	12 毫秒
100k 级扫描	4.2秒	0.4秒

对于大型应用程序，这意味着 HMR 的开发速度明显加快，CI 构建时间也显着缩短。

现实世界的迁移示例

以下是设计系统基本配置的实用前后对比：

// Before: tailwind.config.js (v3)
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          50: '#fef3c7',
          500: '#f59e0b',
          900: '#78350f',
        },
      },
      fontFamily: {
        sans: ['Inter', 'system-ui'],
      },
      boxShadow: {
        card: '0 1px 3px rgba(0,0,0,0.12)',
      },
    },
  },
  plugins: [
    require('@tailwindcss/typography'),
    require('@tailwindcss/forms'),
  ],
};

/* After: globals.css (v4) */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";

@theme {
  --color-brand-50: oklch(97% 0.04 85);
  --color-brand-500: oklch(78% 0.18 85);
  --color-brand-900: oklch(33% 0.08 85);

  --font-sans: 'Inter', system-ui, sans-serif;

  --shadow-card: 0 1px 3px oklch(0% 0 0 / 12%);
}

CSS 原生配置更加简洁，并且消除了读取配置的 node_modules 依赖。

常见问题

我需要立即删除tailwind.config.js吗？

否 — Tailwind v4 在迁移过程中同时支持 JS 配置和 CSS 配置。 JS 配置仍然有效，但 CSS 中的 @theme 等功能只有在没有它的情况下才可用。增量迁移：首先使用 v4 构建应用程序，然后逐渐将配置移至 CSS，然后在有信心时删除 JS 配置。

我现有的 Tailwind v3 类仍然可以在 v4 中使用吗？

绝大多数实用程序类都没有改变。更新了一些颜色名称（在某些情况下为灰色 → 中性），并删除了一些已弃用的实用程序。运行 npx @tailwindcss/upgrade@next 来自动捕获大多数问题。主要的不兼容性在于插件和自定义主题配置，而不在于如何在 HTML/JSX 中使用类。

所有浏览器都支持 OKLCH 吗？

所有现代浏览器（Chrome 111+、Firefox 113+、Safari 15.4+）均支持 OKLCH。 Tailwind v4 在需要时为旧浏览器生成后备。对于 P3 色域（扩展的颜色），支持需要宽色域显示器和支持浏览器 - Tailwind 为窄色域显示器生成 rgb() 后备。

如何将 Tailwind v4 与 shadcn/ui 结合使用？

shadcn/ui 2.0+ 支持 Tailwind v4。更新您的 components.json 以使用 v4 CSS 变量格式。组件库使用 CSS 自定义属性进行主题化，自然映射到 Tailwind v4 的 @theme 系统。在现有项目中运行 npx shadcn@latest init 以获得 v4 兼容的配置。

新配置有 TypeScript 类型吗？

Tailwind v4 的配置是 CSS，因此配置本身没有 TypeScript 类型。 IDE 支持来自理解自定义属性的 CSS 语言服务。要访问 TypeScript 中的主题值（对于图表、动画等），请使用 getComputedStyle 在运行时读取 CSS 自定义属性，或在构建过程中从 CSS 生成令牌文件。

后续步骤

Tailwind CSS v4 是一项重大升级，值得新项目采用并规划现有项目。 ECOSIRE 的前端堆栈在生产环境中跨 249 页的 Next.js 16 应用程序运行 Tailwind CSS v4.1，并具有全面的设计系统。

需要 Tailwind v4 迁移方面的帮助或者想要从头开始构建设计系统？探索我们的前端工程服务以了解我们如何提供帮助。

Tailwind CSS v4: Migration Guide and New Features