Tailwind CSS 4.x 升級指南：v3.4 到 v4.x 遷移重點

這篇會用「可驗證、可落地」的方式，帶你完成 Tailwind CSS 4.x 升級前評估與實作。

前言

如果你最近在看 Tailwind 升級資訊，很容易遇到一個常見混淆：文章標題寫 v4.0，內容卻同時混進 v4.1、v4.2 才有的細節。這樣寫法最大的問題不是「不嚴謹」而已，而是你很難判斷某個做法到底是 4.0 首發就能用，還是必須升到 4.x 的後續版本。

這篇先把邊界講清楚：我們談的是 Tailwind CSS 4.x 升級策略，不是只鎖死在 4.0 首發。也就是說，升級決策會同時考慮 4.0 的架構變化（CSS-first、引擎效能、工具鏈拆分），以及你在 2026 年實際會安裝到的 4.x 穩定版。

截至 2026-04-02，npm 顯示 tailwindcss 的 latest 是 4.2.2，v3-lts 是 3.4.19。因此，多數團隊真正要回答的問題不是「要不要上 4.0」，而是「我們現在要不要從 v3.4 升到 v4.x」。

先定義升級邊界：v4.0 架構變化 vs v4.x 實務版本

升級討論先拆成兩層，決策會比較穩定：

v4.0 架構層：重點是 CSS-first 配置模型、引擎效能改進、工具鏈拆分（CLI/PostCSS/Vite plugin）。
v4.x 版本層：你實際安裝的是哪個穩定版、是否要追最新 patch/minor、團隊是否接受持續更新節奏。

這樣拆的好處是，你可以把「架構遷移」跟「版本節奏」分開管理。先完成架構遷移，再把版本更新納入既有依賴管理流程，不用每次都像大遷移。

升級前先檢查的 4 個前提

1) Browser baseline 是否符合

官方 upgrade guide 已明寫，v4 目標瀏覽器是：

Safari 16.4+
Chrome 111+
Firefox 128+

若你的產品還需要較舊瀏覽器，官方建議先留在 v3.4。這是第一個 gate，沒過就先不要升。

2) 升級工具與執行環境

官方 @tailwindcss/upgrade 需要 Node.js 20+。如果你的 CI 或本機環境還在 Node 18，請先升 Node，再談自動升級。

3) 工具鏈是否能接受套件拆分

v4 把職責拆開了：

PostCSS plugin：@tailwindcss/postcss
CLI：@tailwindcss/cli
Vite plugin：@tailwindcss/vite

這代表你要檢查 package.json、postcss.config.*、vite.config.* 是否能同步調整。

4) 團隊是否有回歸驗證

至少要有：

主要頁面視覺快照或 smoke test
Design token 變更點清單
升級分支與可回退 lockfile

沒有這三件事，升級風險通常不在 Tailwind 本身，而在你無法快速定位回歸。

實作步驟：從 v3.4 到 v4.x

步驟 1：開升級分支並執行官方工具

# 建議先切新分支
git checkout -b chore/tailwind-v4-upgrade

# Node.js 20+ 環境執行
npx @tailwindcss/upgrade@latest

官方也建議在新分支執行，因為工具會同時改相依與設定，方便你 review diff。

步驟 2：依你的整合方式調整設定

以 PostCSS 專案為例：

// postcss.config.mjs
export default {
  plugins: {
    // v4 改用獨立的 PostCSS 插件套件
    "@tailwindcss/postcss": {},
  },
};

如果你是 Vite 專案：

// vite.config.ts
import { defineConfig } from "vite";
import tailwindcss from "@tailwindcss/vite";

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

如果你是 CLI 流程：

# v4 CLI 套件名稱已改
npx @tailwindcss/cli -i ./src/input.css -o ./src/output.css --watch

步驟 3：確認 CSS-first 不是「只能用 CSS」

v4 的核心是 CSS-first，但不是「完全不能用 JS config」。官方仍提供 @config、@plugin，可跟 CSS 設定併用。

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

/* 中文註解：沿用既有 JS config，降低一次性重構風險 */
@config "../tailwind.config.js";

/* 中文註解：既有 plugin 仍可透過 directive 載入 */
@plugin "@tailwindcss/typography";

@theme {
  --color-brand-500: oklch(0.62 0.2 262);
}

實務上建議「漸進遷移」：先讓系統可運作，再逐步把 token/utility 轉到 CSS-first，不要一次全改。

常見踩雷與修正方式

踩雷 1：把不可驗證效能數字當成 KPI

若要談效能，請引用官方 v4.0 benchmark（Catalyst 測試）：

Full build：378ms -> 100ms（3.78x）
Incremental rebuild（new CSS）：44ms -> 5ms（8.8x）
Incremental rebuild（no new CSS）：35ms -> 192µs（182x）

重點是「測試基準要一起寫出來」，不要直接把數字套到每個團隊。

踩雷 2：把不存在的 utility 當成內建 API

ms-4、me-4、ps-4、pe-4 在 v4 可用；但像 inline-size-[200px] 這種格式不是內建 utility 命名。

如果你要示範 writing-mode 尺寸，建議明確寫成 arbitrary property：

<!-- 中文註解：這是 arbitrary property，不是內建 inline-size-* utility -->
<div class="[inline-size:200px] [block-size:100px] ms-4 me-4"></div>

這樣讀者才不會誤以為 inline-size-* 是官方 utility family。

踩雷 3：忽略相依拆分後的遺留設定

升級後常見遺留：

PostCSS 仍保留舊 tailwindcss plugin 設定
build script 仍呼叫舊 CLI 命令
團隊文件沒更新，導致新成員照舊流程失敗

建議在升級 PR 一次補齊 README 或 CONTRIBUTING 的開發指令。

常見問題 / 注意事項

Q1：什麼情況建議暫留 v3.4？

產品仍需支援低於官方 baseline 的瀏覽器
CI / 部署環境短期無法升到 Node 20+
近期正在大改 UI token 或設計系統，不適合同時做工具鏈遷移

Q2：要直接衝最新 4.x，還是先上 4.0？

多數團隊可直接上當下 latest 穩定版（截至 2026-04-02 為 4.2.2），但要固定 lockfile、跑完整回歸。

Q3：升級後一定要完全移除 JS config 嗎？

不用。可以先透過 @config / @plugin 兼容舊設定，再逐步收斂到 CSS-first。

總結

Tailwind CSS 升級最怕的不是 breaking change，而是「版本邊界不清楚 + 缺少可驗證流程」。

這次建議你記住三件事：

先把主題定義成 v4.x 升級，避免混淆 4.0 與後續版本。
先檢查官方前提（browser baseline、Node 20+、工具鏈拆分）再動手。
用升級分支 + 回歸測試 + 文件同步，把遷移變成可重複流程。

做完這三步，你就不會把 Tailwind 升級當成一次性賭注，而是團隊可以持續維護的工程節奏。