技術 6 分鐘閱讀

Tailwind CSS v4 升級指南：新功能與遷移步驟

2026年1月10日

前言

Tailwind CSS v4 是一次重大的版本更新，底層引擎完全重寫，效能大幅提升，設定方式也有顯著變化。這篇文章整理了最重要的變更和遷移步驟。

v4 的重大變更

1. 不再需要設定檔

v4 最大的變化是設定從 JavaScript 移到了 CSS：

/* v3 的方式：tailwind.config.js */
/* v4 的方式：直接在 CSS 中設定 */

@import "tailwindcss";

@theme {
  --color-primary-500: #3b82f6;
  --color-primary-600: #2563eb;
  --color-primary-700: #1d4ed8;

  --font-family-sans: 'Noto Sans TC', sans-serif;

  --breakpoint-sm: 640px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 1024px;
}

這讓設定更直覺，也更容易跟 CSS 生態系整合。

2. 全新的引擎

v4 使用了全新的 Oxide 引擎（Rust 重寫），帶來的改進：

建置速度提升 10 倍
增量編譯：只處理變更的部分
更小的 CSS 輸出
自動內容偵測：不再需要手動設定 content 路徑

3. 原生 CSS 功能

v4 大量採用了現代 CSS 的功能：

/* 原生巢狀 CSS */
.card {
  background: white;

  &:hover {
    background: #f3f4f6;
  }

  & .title {
    font-size: 1.25rem;
  }
}

/* 原生 CSS 層疊層 */
@layer base, components, utilities;

4. 新的 Utility 語法

一些 class 名稱有變更：

<!-- v3 -->
<div class="bg-opacity-50">
<div class="text-opacity-75">

<!-- v4：使用 CSS 原生語法 -->
<div class="bg-blue-500/50">
<div class="text-gray-900/75">

遷移步驟

第一步：更新套件

npm install tailwindcss@latest

第二步：使用自動遷移工具

Tailwind 提供了官方的遷移工具：

npx @tailwindcss/upgrade

這個工具會自動處理大部分的變更：

將 tailwind.config.js 的設定轉換到 CSS
更新已棄用的 class 名稱
調整 PostCSS 設定

第三步：手動檢查

自動遷移工具無法處理所有情況，需要手動檢查：

主題設定遷移

// v3 tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: {
          light: '#85d7ff',
          DEFAULT: '#1fb6ff',
          dark: '#009eeb',
        },
      },
      spacing: {
        '72': '18rem',
        '84': '21rem',
      },
    },
  },
};

轉換為：

/* v4 CSS */
@import "tailwindcss";

@theme {
  --color-brand-light: #85d7ff;
  --color-brand: #1fb6ff;
  --color-brand-dark: #009eeb;

  --spacing-72: 18rem;
  --spacing-84: 21rem;
}

外掛遷移

v4 的外掛系統也有變更：

// v3 外掛
const plugin = require('tailwindcss/plugin');

module.exports = plugin(function({ addUtilities }) {
  addUtilities({
    '.text-balance': {
      'text-wrap': 'balance',
    },
  });
});

/* v4：直接用 CSS @utility */
@utility text-balance {
  text-wrap: balance;
}

第四步：更新 PostCSS 設定

// v3 postcss.config.js
module.exports = {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

// v4：簡化了，autoprefixer 已內建
module.exports = {
  plugins: {
    tailwindcss: {},
  },
};

第五步：更新 CSS 入口檔案

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

/* v4 */
@import "tailwindcss";

新功能亮點

容器查詢

<div class="@container">
  <div class="@sm:flex @lg:grid @lg:grid-cols-2">
    <!-- 根據容器寬度而非視窗寬度調整佈局 -->
  </div>
</div>

3D 變換

<div class="rotate-x-12 rotate-y-6 perspective-500">
  3D 效果
</div>

原生 CSS 變數整合

<div class="bg-[--my-color]" style="--my-color: #ff6b6b;">
  使用 CSS 變數
</div>

常見的遷移問題

1. 自訂色彩格式

v4 要求顏色值必須是標準 CSS 格式：

/* v3 允許 */
--color-primary: 59 130 246;

/* v4 要求標準格式 */
--color-primary: #3b82f6;
--color-primary: rgb(59, 130, 246);
--color-primary: oklch(0.63 0.19 252);

2. 深色模式

/* v4 的深色模式設定 */
@import "tailwindcss";

@variant dark (&:where(.dark, .dark *));

3. 重要度標記

<!-- v3 -->
<div class="!text-red-500">

<!-- v4：語法相同，但內部實作改用 CSS 層疊層 -->
<div class="!text-red-500">

是否該立即升級？

建議升級的情況

新專案直接用 v4
專案較小，遷移成本低
想要更好的建置效能

可以暫緩的情況

大型專案，使用大量自訂外掛
依賴的 UI 套件還沒支援 v4
專案即將交付，不適合大幅更動

結語

Tailwind CSS v4 是一次重要的進化。雖然遷移需要一些工作，但新的引擎帶來的效能提升和更簡潔的設定方式，長期來看絕對值得。建議在新專案中直接採用 v4，既有專案則等穩定一段時間後再逐步遷移。

#Tailwind CSS #CSS #前端開發 #升級

Thousand Lab

GitHub LINE

前言