Tailwind CSS 4.0 升級指南：CSS-first 時代來臨

Tailwind CSS 4.0 的最大變化，不是「多了一百個新 utility class」——而是配置方式的根本改變。過去 Tailwind CSS 的配置在 tailwind.config.js 裡，用 JavaScript 定義你的設計系統。4.0 把這個配置帶到了 CSS 裡，用 @theme directive 來定義。這不是一個微小的語法變化——這是 Tailwind 團隊對「CSS 應該如何工作」的理解的改變。

為什麼 Tailwind CSS 4.0 值得關注

過去的痛點

Tailwind CSS v3 的配置需要在一個獨立的 JS 檔案裡管理：

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#4f46e5',
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', 'sans-serif'],
      },
    },
  },
  plugins: [],
};

這個方式的問題：

配置和樣式分離：你在 CSS 裡寫 class，在 JS 裡配置設計系統
編譯速度瓶頸：v3 的編譯在大型專案裡開始變慢
CSS 功能受限：某些 CSS 功能（如 @layer）需要繞過 JS 配置

4.0 的回答

Tailwind CSS 4.0 選擇將配置帶回 CSS：

/* 4.0：所有配置都在 CSS 裡 */
@import "tailwindcss";

@theme {
  --color-brand: #4f46e5;
  --font-sans: "Inter", system-ui, sans-serif;
}

這個改變的意義：CSS-first。當你在一個 CSS 檔案裡工作時，你的配置就在同一個地方。

@theme：設計系統的 CSS 表達

@theme directive

@import "tailwindcss";

@theme {
  /* 顏色 */
  --color-brand-50: #eef2ff;
  --color-brand-100: #e0e7ff;
  --color-brand-500: #4f46e5;
  --color-brand-900: #312e81;

  /* 字體 */
  --font-sans: "Inter", system-ui, sans-serif;
  --font-display: "Inter", system-ui, sans-serif;

  /* 間距 */
  --spacing-128: 32rem;

  /* 圓角 */
  --radius-xl: 1rem;
  --radius-2xl: 1.5rem;

  /* 陰影 */
  --shadow-card: 0 4px 6px -1px rgb(0 0 0 / 0.1);
}

使用自訂主題

<!-- 直接使用你定義的 token -->
<button class="bg-brand-500 text-white font-sans rounded-xl shadow-card">
  Button
</button>

與 v3 的 extend 語法對比

// v3：extend 在 JS 裡
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: '#4f46e5',
      },
    },
  },
};

/* v4：@theme 在 CSS 裡，覆蓋而非合併 */
@theme {
  --color-brand: #4f46e5;
}

Oxide 引擎：效能提升

編譯速度

4.0 的 Oxide 引擎讓編譯速度大幅提升：

專案規模	v3 編譯時間	v4 編譯時間	提升
小型（50 個 CSS 檔案）	200ms	50ms	4x
中型（200 個 CSS 檔案）	800ms	120ms	6.6x
大型（1000 個 CSS 檔案）	4s	400ms	10x

這個提升來自 Oxide 引擎的重寫——使用 Rust 開發的解析器和編譯器。

對開發者的影響

# 大型專案的時間節省
# v3：等待編譯
# 估計每週浪费 3-5 小時等待時間

# v4：几乎即时
# 同樣等待時間减少到接近零

Tailwind CSS v4.2 新功能

@tailwindcss/webpack 支援

// webpack 配置
// v4.2 原生支援 webpack，不需要額外設定
module.exports = {
  module: {
    rules: [
      {
        test: /\.css$/,
        use: ['@tailwindcss/webpack'],
      },
    ],
  },
};

4 個新色彩面板

@theme {
  /* 新增的 color palette */
  --color-amber-50: #fffbeb;
  --color-amber-100: #fef3c7;
  /* ... */

  /* 現在支援 12 個語意化色彩 */
  --color-success: oklch(70% 0.15 145);
  --color-warning: oklch(75% 0.18 85);
  --color-error: oklch(65% 0.25 25);
}

Logical Property Utilities

<!-- 邏輯屬性：支援 RTL 和 LTR -->
<div class="ms-4 me-4 ps-4 pe-4">
  <!-- ms = margin-inline-start -->
  <!-- me = margin-inline-end -->
  <!-- ps = padding-inline-start -->
  <!-- pe = padding-inline-end -->
</div>

Inline/Block Size Utilities

/* 新增的 size utilities */
<div class="inline-size-[200px] block-size-[100px]">
  <!-- inline-size = width in horizontal writing -->
  <!-- block-size = height -->
</div>

遷移到 v4：實際步驟

官方升級工具

# 1. 安裝官方升級工具
npx @tailwindcss/upgrade@latest

# 2. 執行升級
# 工具會自動：
# - 將 tailwind.config.js 轉換為 @theme 語法
# - 更新相依性
# - 處理大多數 breaking changes

# 3. 驗證
npm run dev

自動處理的項目

@apply 語法
tailwind.config.js 的 theme.extend 轉換
Plugin 配置
常用 patterns

需要手動調整的項目

/* 複雜的 CSS-in-JS 配置可能需要手動處理 */

/* v3 */
module.exports = {
  theme: {
    extend: {
      backgroundImage: {
        'gradient-radial': 'radial-gradient(var(--tw-gradient-stops))',
      },
    },
  },
};

/* v4 */
@theme {
  --gradient-radial: radial-gradient(var(--tw-gradient-stops));
}

複雜專案的遷移策略

# 1. 先升級到 v3 的最新版本
npm install tailwindcss@3

# 2. 確保所有測試通過
npm test

# 3. 使用官方工具升級
npx @tailwindcss/upgrade@latest

# 4. 處理任何 breaking changes
# 查閱官方 Migration Guide

# 5. 驗證所有視覺效果
npm run dev

結語：CSS-first 的意義

Tailwind CSS 4.0 的 CSS-first 轉變，代表了一個更廣的趨勢：配置正在回歸 CSS。

過去十年，前端工具傾向於把配置放在 JavaScript 裡——webpack config、babel config、postcss config、tailwind config。這個方式的優點是「強大的程式化配置能力」，缺點是「配置和樣式分離」。

CSS-first 的回歸，是對「樣式應該在 CSS 裡定義」這個基本原則的重新確認。Tailwind CSS 4.0 的 @theme 語法，讓設計系統的配置成為 CSS 檔案的一部分，而不是一個獨立的 JS 檔案。

對於正在使用 Tailwind CSS v3 的專案，v4 的升級成本已經大幅降低——官方升級工具可以自動處理大部分遷移工作。對於新專案，v4 是更推薦的選擇。