Tailwind CSS v4 完整升級教學：從 v3 遷移到 v4 的新功能與實戰攻略

Tailwind CSS v4 終於在 2025 年底正式發布了，而到了 2026 年初，整個生態系也漸漸穩定下來。身為從 Tailwind v1 就開始用的老用戶，我可以說這次 v4 的改動是有史以來最大的一次——不只是加了新功能，而是底層架構整個重寫了。

這篇會把 v4 的所有重要改動都講清楚，同時提供從 v3 遷移的完整步驟。如果你的專案還在 v3，看完這篇就能評估要不要升級、以及怎麼升級。

Tailwind CSS v4 到底改了什麼

先給一個全景概覽。v4 的核心變化可以歸納為五大方向：

1. CSS-first 設定：告別 tailwind.config.js，設定直接寫在 CSS 裡
2. 新引擎：從 PostCSS 外掛改為基於 Lightning CSS 的獨立引擎
3. 原生 CSS 功能：擁抱 @layer、@property、Container Queries 等原生標準
4. 色彩系統升級：從 HSL 切換到 OKLCH 色彩空間
5. 效能飛躍：build 速度最高快 10 倍以上

我自己在幾個專案上升級後的感受是：一旦適應了新的設定方式，整個開發體驗確實變好了。尤其是 CSS-first 設定讓設定檔看起來更直覺，不再需要跟 JavaScript 物件語法搏鬥。

CSS-first 設定檔革命

這大概是 v4 最有感的改動。以前你需要一個 tailwind.config.js 來自訂主題、外掛、內容路徑等等，現在這些都搬到 CSS 檔案裡了。

v3 的做法：

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{html,js,tsx}'],
  theme: {
    extend: {
      colors: {
        brand: '#6366f1',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
}

v4 的做法：

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

@theme {
  --color-brand: #6366f1;
  --font-sans: 'Inter', sans-serif;
}

看到差異了嗎？v4 用 @theme 指令搭配 CSS 自訂屬性的語法，不再需要 JavaScript 設定檔。這帶來幾個好處：你的 IDE 可以直接解析 CSS 語法、不需要額外的 TypeScript 型別支援、設定和樣式在同一個檔案裡更容易維護。

內容掃描路徑（content paths）也變了。v4 預設會自動偵測你的專案結構，大部分情況下不需要手動設定。如果真的需要自訂，可以用 @source 指令。

Lightning CSS 引擎帶來的效能飛躍

v4 最底層的改動是引擎的更換。之前 Tailwind 是作為 PostCSS 外掛運行的，現在它有自己的獨立 CSS 處理引擎，底層基於用 Rust 寫的 Lightning CSS。

這帶來的直接好處就是速度。根據 Tailwind Labs 官方的 benchmark：

• 初次 build：快 3.5 倍
• 增量 build（HMR）：快 8 倍以上
• 大型專案（10 萬行以上）：快 10 倍

我自己在一個中型 Next.js 專案上的實測數據：v3 的完整 build 大約 2.8 秒，v4 降到 0.7 秒左右。HMR 更是從明顯的延遲變成幾乎即時。

另一個好處是 Lightning CSS 自帶很多 PostCSS 外掛的功能，例如 autoprefixer、CSS nesting、custom media queries。這意味著你可以移除這些 PostCSS 外掛的相依性，簡化 build pipeline。

原生 CSS @layer 整合

v4 全面採用了 CSS 原生的 @layer 規則來管理樣式的優先權。Tailwind 的三大層——base、components、utilities——現在都用原生 @layer 來實作。

這跟 v3 有什麼差別？v3 用自己的機制來處理優先權，而 v4 直接利用瀏覽器原生的層疊規則。這意味著你可以更精確地控制 Tailwind 樣式跟你自定義樣式之間的優先權關係。

如果你對 CSS @layer 還不熟，推薦先看看我們之前寫的 CSS @layer 層疊圖層完整教學。

實務上最常見的用法是：當你有一些第三方 UI 元件的樣式需要覆蓋時，可以把它們放在正確的 layer 中，確保 Tailwind 的 utility class 永遠有最高優先權。

全新色彩系統 OKLCH

v4 把預設的色彩空間從 HSL 切換到了 OKLCH（OK Lightness Chroma Hue）。這個改動可能對一般使用者影響不大，但對進階的設計實作來說是一個大進步。

OKLCH 的優勢在於感知一致性——相同的 lightness 值在不同色相之間看起來確實是差不多亮的。HSL 的問題是 50% lightness 的黃色看起來就是比 50% lightness 的藍色亮很多，這導致用程式生成色階時容易出現不和諧的顏色。

v4 的色彩相關 utility 也做了對應的更新。例如你可以直接使用 OKLCH 的 opacity 修飾符，而不需要依賴 --tw-bg-opacity 這種 CSS 變數 hack。搭配 CSS @property 自訂屬性，可以做出更精細的色彩動畫效果。

Container Queries 原生支援

v3 需要用 @tailwindcss/container-queries 外掛才能使用 Container Queries，v4 直接內建支援了。語法也更簡潔：

<div class="@container">
  <div class="@sm:grid-cols-2 @lg:grid-cols-3">
    <!-- 根據容器寬度而非視窗寬度來響應 -->
  </div>
</div>

Container Queries 對於元件級的響應式設計非常重要。以前用 media queries 只能根據視窗寬度來決定排版，但同一個元件放在側邊欄和主內容區寬度完全不同。Container Queries 讓元件可以根據自己的容器寬度來調整，實現真正的元件級響應。

更詳細的用法可以參考 Tailwind CSS v4 Container Queries 完整教學。

新增實用 utility class

v4 新增了不少 utility class，以下是我最常用的幾個：

• text-wrap: balance：text-balance class，讓標題文字自動平衡換行
• Subgrid 支援：subgrid class，讓巢狀 grid 可以繼承父層的 grid track
• Field-sizing：field-size-content，讓 textarea 自動根據內容調整高度
• Anchor positioning：搭配 CSS Anchor Positioning 使用的定位 utility
• Starting style：starting: modifier，用於 CSS transition 的起始狀態

其中 text-balance 是我每個專案都會用到的，只要加一個 class 就能讓多行標題不再出現一行超長一行超短的尷尬情況。

從 v3 遷移到 v4 的完整步驟

Tailwind 官方提供了一個自動遷移工具，但根據我的經驗，最好還是搭配手動檢查。以下是完整步驟：

1. 升級相依套件：npm install tailwindcss@latest
2. 執行官方遷移工具：npx @tailwindcss/upgrade。這會自動把 tailwind.config.js 轉換成 CSS 設定，並更新已棄用的 class 名稱
3. 移除不再需要的 PostCSS 外掛：autoprefixer、postcss-import 通常可以移除
4. 更新 PostCSS 設定：如果你的框架用 PostCSS，設定方式可能要調整
5. 檢查自訂 @apply 使用：v4 的 @apply 行為有些微變動
6. 檢查 darkMode 設定：v4 預設使用 media 策略，如果你用 class 策略要確認設定
7. 測試！測試！測試！：所有頁面都跑一遍，重點看排版和顏色有沒有跑掉

Breaking Changes 踩坑整理

以下是我實際升級時踩到的坑：

@apply 在 @layer 中的行為：v4 裡 @apply 在 CSS @layer 中使用時，應用的 utility 會繼承 layer 的優先權而非 utility layer 的優先權。如果你有大量使用 @apply 來建立自訂元件 class，要特別注意。

預設 border 顏色：v3 預設的 border 顏色是 gray-200，v4 改成了 currentColor。如果你有很多 border class 沒有指定顏色，升級後可能會發現邊框突然變黑了。

Ring utility 預設值：ring 的預設寬度和顏色也改了，需要檢查所有使用 ring 的地方。

opacity utility 語法：以前的 bg-red-500/50 語法還是支援的，但底層實作方式改了。如果你有用 CSS 變數來控制 opacity，需要更新。

效能對比實測

在我們的幾個專案上做了 build 效能對比：

小型專案（約 50 個頁面）：v3 build 1.2s → v4 build 0.3s（快 4 倍）

中型專案（約 200 個頁面）：v3 build 2.8s → v4 build 0.7s（快 4 倍）

大型專案（約 800 個頁面 + 完整設計系統）：v3 build 8.5s → v4 build 1.1s（快 7.7 倍）

HMR 的改善更加明顯，在大型專案上從肉眼可見的延遲變成幾乎即時。對開發體驗的提升是實實在在的。

CSS 產出大小也有所減少，因為 Lightning CSS 的壓縮算法更好，加上原生 @layer 不需要額外的 specificity hack。

生態系相容性更新

最後講一下生態系的支援狀況。到 2026 年 Q1，主要的框架和工具都已經支援 Tailwind v4：

• Next.js 15：完整支援，且推薦使用 v4
• Nuxt 3：透過 @nuxtjs/tailwindcss v7 支援
• Vite：原生支援，效能最佳
• shadcn/ui：已更新到 v4 相容版本
• Headless UI：完整支援
• Radix UI：完整支援

如果你用的是比較冷門的框架或元件庫，升級前建議先確認一下它們的 v4 支援狀態。大部分的問題都集中在 PostCSS 設定和 @apply 的使用上，邏輯程式碼通常不需要修改。

整體來說，Tailwind CSS v4 是一次值得升級的大版本更新。CSS-first 設定讓開發體驗更直覺，Lightning CSS 引擎讓 build 速度飛躍式提升，對原生 CSS 標準的擁抱也讓 Tailwind 的未來更有可持續性。如果你的專案還在 v3，現在是個好時機開始規劃升級了。