Tailwind CSS v4 升級指南 — 速度更快、體積更小、寫法更自由

v4 推出一年後的升級重點整理:設定從 JS 檔改成在 CSS 的 @theme 裡定義變數,舊的 tailwind.config.js 仍可透過 @config 沿用。

本篇目錄

Tailwind CSS v4 重新設計了 CSS 引擎,保留 Utility-First 的使用方式,也調整了配置方式與建置效能。

v4.0 在 2025 年 1 月正式發布。推出一年、生態系與周邊工具跟上之後,我回頭整理了升級重點,著重在實際搬遷時容易卡住的地方。

設定方式與建置效能

v4 把預設的配置方式從 JavaScript 設定檔換成了 CSS 變數。舊的 tailwind.config.js 仍可透過 @config 指令沿用,但新專案可以直接在 CSS 裡用 @theme 設定。

官方 v4 發布文章提到,完整建置最高約快 5 倍,未新增 CSS 的增量建置則超過 100 倍。文中以 Catalyst 測試得到的中位數分別是 3.78 倍和 182 倍;有新增 CSS 時的增量建置則是 8.8 倍。這些是官方專案的測試結果,自己的專案還是要實際量測。

引擎也不是全部改成 Rust。官方的架構說明提到,部分耗時且適合平行處理的工作改用 Rust,核心仍保留 TypeScript,並整合 Lightning CSS 處理樣式。

至於只產生用到的 utility,v3 的 JIT 就已經這樣做。同一篇架構說明提到新引擎安裝後小了 35% 以上,這指的是套件的安裝大小,和產出的 CSS 無關。升級後的 CSS 是否更小,要比較自己的產出,不能光看版本號判斷。

全新的配置方式

以前我們要定義顏色、斷點,都要去 tailwind.config.js 改。現在可以直接在 CSS 檔裡用 @theme 區塊定義:

@import "tailwindcss";

@theme {
  --color-brand-primary: #ff5722;
  --font-sans: "Inter", sans-serif;
  --spacing-128: 32rem;
}

然後你就可以直接用 text-brand-primary、font-sans 或 p-128。

這裡的變數前綴不能亂取,它決定了會生成哪一組 utility:--color-* 對應 text-*/bg-*/border-*,--font-* 對應 font-*,--spacing-* 對應 p-*/m-*/gap-*。要設定 font-sans,變數名稱是 --font-sans。 如果誤寫成 --font-family-sans,對應的 class 會變成 font-family-sans, 不會改到原本想設定的 font-sans。可以對照官方命名空間表確認名稱。

任意值語法與 CSS 運算

其實方括號任意值語法(例如 w-[350px])與其中的 CSS 運算(calc()),從 2021 年推出的 JIT 引擎就開始支援了:v2.1 用 mode: "jit" 選用,v3 起 JIT 成為預設引擎。

<div class="w-[calc(100%-20px)] bg-brand-primary/50">...</div>

注意那個 /50:v4 底層改用 color-mix() 處理透明度,因此即使顏色是用 CSS 變數表示,/50 這類修飾語也能正常運作,不再需要額外的 hack。

v4 也讓不少 utility 直接接受動態數值,例如 w-17、grid-cols-15,不必再寫成方括號的任意值。原本的任意值則有兩處寫法要改:CSS 變數簡寫從 bg-[--brand-color] 改成 bg-(--brand-color);grid-cols-*、grid-rows-*、object-* 的任意值不再把逗號轉成空格,要改用底線,例如 grid-cols-[max-content_auto]。

容器查詢(Container Queries)正式內建

以前要用 @tailwindcss/container-queries 外掛,現在直接內建:

<div class="@container">
  <div class="@lg:grid-cols-2 grid">
    <!-- 當父容器大於 lg 時變兩欄 -->
  </div>
</div>

3D 變換(3D Transforms)

v4 增加了對 3D 屬性的支援:

<div class="transform-3d rotate-x-12 rotate-y-24">...</div>

這類旋轉可以直接用 class 組合,需要時也能自己寫 transform: rotateX(...)。

升級指南

如果專案還在用 v3,先確認目標瀏覽器是否符合 v4 的要求:Safari 16.4、Chrome 111、Firefox 128 以上。需要支援更舊的瀏覽器時,可以先留在 v3.4。

官方遷移工具需要 Node.js 20 以上。建議在獨立分支執行,方便檢查變更:

npx @tailwindcss/upgrade

工具會協助更新相依套件、搬移設定與調整模板,但執行完還要看 diff、建置專案,並打開實際頁面確認。尤其要留意 border 的預設顏色、ring 的寬度,以及 shadow、rounded 等 utility 的命名調整;程式沒有報錯,畫面也可能和 v3 不同。

PostCSS 與 CLI 的整合套件也有變動,不能只轉換 tailwind.config.js 就算完成。遷移時可以逐項對照官方升級指南。

結語

對我來說,把設定放進 CSS,是 v4 最有感的改變。新專案可以直接從 @theme 開始;既有專案則先確認瀏覽器支援範圍,再用遷移工具處理大部分修改,把時間留給畫面與互動的檢查。


站內相關文章: