Tailwind CSS v4 新功能完整教學：升級指南與實戰範例

前言：為什麼 Tailwind CSS v4 值得你立刻升級？

如果你是前端開發者，這幾年應該很難避開 Tailwind CSS 的討論。它用 utility-first 的設計哲學改變了我們寫樣式的方式，而現在，Tailwind CSS v4 帶來了自發布以來最大規模的架構重構。更快的編譯速度、全新的設定方式、原生支援 Container Queries——這不只是版本號的跳躍，更是整個開發體驗的躍升。

這篇文章會帶你完整了解 Tailwind CSS v4 的新功能，並提供從 v3 升級的實戰指南。無論你是從零開始，還是需要把現有專案遷移過來，都能在這裡找到所需的資訊。

CSS-first 設定：告別 tailwind.config.js

Tailwind v4 最顛覆性的改變，大概就是把設定檔從 JavaScript 搬回了 CSS。過去，我們習慣在 tailwind.config.js 裡定義顏色、字型、斷點等設計令牌（design tokens），現在這些全部可以直接寫在 CSS 裡。

這不只是語法糖，背後的意義是：你的設計系統現在完全活在 CSS 規範之內，不再需要一個額外的 JavaScript 層來橋接。

以下是一個典型的 v4 設定範例：

/* app.css */
@import "tailwindcss";

@theme {
  --color-brand: #6366f1;
  --color-brand-dark: #4f46e5;
  --font-display: "Cal Sans", sans-serif;
  --spacing-18: 4.5rem;
  --breakpoint-3xl: 1920px;
}

透過 @theme 區塊，你可以直接用 CSS 自訂屬性（custom properties）定義你的設計令牌。這些變數會自動被 Tailwind 解析，產生對應的 utility class。例如定義了 --color-brand，你就可以直接用 bg-brand、text-brand、border-brand。

對於從 v3 遷移的專案，你可以先保留 tailwind.config.js 並逐步搬移，或者使用官方提供的 codemod 工具一次性完成轉換。

5 倍速度提升：Oxide 引擎的威力

Tailwind v4 底層採用了全新的 Oxide 引擎，官方數據顯示編譯速度比 v3 快了將近 5 倍。這個數字聽起來很誇張，但背後有具體的技術支撐。

Oxide 引擎的核心改進包括：

• 增量編譯：只重新編譯有變動的部分，而非每次都全量掃描
• Rust 底層實作：部分核心解析邏輯使用 Rust 撰寫，大幅降低 CPU 開銷
• 更智慧的 class 偵測：掃描邏輯更精準，減少誤判和重複處理

在大型專案中，這個速度差異會非常明顯。過去可能要等 1-2 秒才能看到樣式更新，現在幾乎是即時反映。這對於開發體驗的影響是實質性的，特別是在你頻繁調整樣式的時候。

實際測試一個包含 200+ 個元件的 Next.js 專案，冷啟動時間從約 3.2 秒降到 0.6 秒，熱更新則幾乎感覺不到延遲。

原生 Container Queries：響應式設計的新思維

這個功能讓我最興奮。Tailwind v4 內建支援 CSS Container Queries，不再需要額外安裝 @tailwindcss/container-queries 外掛。

Container Queries 允許你根據父容器的尺寸而非視窗寬度來套用樣式，這解決了響應式元件設計中的一個根本問題：元件不應該依賴全域視窗尺寸，而應該根據它所在的容器來決定自己的樣式。

在 v4 中，語法非常直覺：

<div class="@container">
  <div class="@sm:flex @md:grid @lg:grid-cols-3">
    <!-- 根據父容器寬度自動調整佈局 -->
  </div>
</div>

你只需要在父元素加上 @container，子元素就可以使用 @sm:、@md:、@lg: 等前綴來設定響應式樣式。Tailwind v4 預設提供了一組 container 斷點，你也可以在 @theme 中自訂：

@theme {
  --container-breakpoint-card-sm: 300px;
  --container-breakpoint-card-lg: 600px;
}

這項功能配合元件化開發特別強大。一個卡片元件可以在側邊欄中顯示為垂直排列，放到主內容區就自動變成水平佈局——不需要任何 JavaScript，純粹靠 CSS 完成。想深入了解 Container Queries 的應用場景，可以參考這篇Container Queries 完整響應式設計教學。

統一工具鏈：安裝設定更簡單

在 Tailwind v3 時代，你需要同時安裝 tailwindcss、postcss、autoprefixer，再設定 postcss.config.js。整個設定流程對新手來說頗為繁瑣，也容易因版本不相容產生奇怪的問題。

Tailwind v4 解決了這個問題。它提供了統一的工具鏈，對於 Vite 專案，安裝幾乎只需要兩個步驟：

# 安裝套件
npm install tailwindcss @tailwindcss/vite

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

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

不再需要獨立的 PostCSS 設定，不再需要 autoprefixer（v4 內建處理瀏覽器前綴），一個 Vite 外掛搞定一切。對於非 Vite 的專案，也有對應的 PostCSS 外掛可以使用，但 API 大幅簡化了。

這種統一工具鏈的做法，讓 Tailwind 能更好地控制整個編譯流程，這也是 Oxide 引擎能發揮效能的原因之一。

Runtime Theme Switching：動態主題不再麻煩

Dark mode 支援在 v3 就有了，但 v4 的 Runtime Theme Switching 把這個概念提升到了新的層次。由於設計令牌現在是真正的 CSS 自訂屬性，你可以在執行時期動態切換整個主題——不只是深色/淺色，而是完整的品牌主題切換。

@theme {
  --color-primary: #6366f1;
  --color-bg: #ffffff;
  --color-text: #111827;
}

[data-theme="dark"] {
  --color-primary: #818cf8;
  --color-bg: #111827;
  --color-text: #f9fafb;
}

[data-theme="ocean"] {
  --color-primary: #0ea5e9;
  --color-bg: #f0f9ff;
  --color-text: #0c4a6e;
}

切換主題只需要更改 data-theme 屬性：

// 切換到深色主題
document.documentElement.setAttribute('data-theme', 'dark')

// 切換到海洋主題
document.documentElement.setAttribute('data-theme', 'ocean')

由於這完全基於原生 CSS 變數，主題切換是即時的，沒有任何閃爍或重新渲染的問題。這在需要多品牌支援的 SaaS 產品或白標應用中特別有用。

搭配 CSS 動畫讓主題切換更流暢也非常簡單，可以參考這篇CSS 動畫完整教學來了解如何加入過渡效果。

從 v3 升級到 v4：實戰遷移指南

升級的過程比你想像的順暢，官方也提供了自動化工具輔助。以下是建議的遷移步驟：

步驟一：使用 Upgrade 工具

npx @tailwindcss/upgrade@next

這個工具會自動處理大部分的破壞性變更，包括將 tailwind.config.js 轉換為 CSS @theme 語法，以及更新已廢棄的 class 名稱。

步驟二：更新 CSS 入口檔案

/* 舊版 v3 */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* 新版 v4 */
@import "tailwindcss";

步驟三：處理破壞性變更

v4 有幾個值得注意的破壞性變更：

• shadow-sm 改為 shadow-xs，shadow 改為 shadow-sm（整體縮放調整）
• 部分顏色名稱更新，如 slate-50 的實際色值有微調
• ring 預設寬度從 3px 改為 1px
• Preflight 樣式有部分更新，需要檢查全域樣式是否受影響

建議升級後先跑一遍視覺回歸測試，確保沒有意外的樣式變化。在佈局方面，如果你有複雜的 Grid 配置，可以參考CSS Grid 完整教學確認 v4 的 Grid utility 用法是否有變動。

結語：v4 是值得立刻升級的版本

Tailwind CSS v4 不只是功能累積，而是對整個架構的重新思考。CSS-first 的設定方式讓設計系統更加透明，5 倍速度提升讓開發過程更流暢，內建 Container Queries 讓響應式設計進入新紀元，統一工具鏈則大幅降低了設定成本。

對於新專案，現在就應該直接從 v4 開始。對於既有專案，在有足夠測試覆蓋的情況下，建議在下一個版本迭代中安排升級。官方的 upgrade 工具已經相當成熟，大多數情況下可以一鍵完成主要的遷移工作。

前端工具鏈的演進速度很快，但 Tailwind CSS v4 這次的改動方向是對的——它在讓工具更強大的同時，也讓開發者的工作變得更簡單。這正是好工具應該有的樣子。