Tailwind CSS v4 遷移完全指南：新引擎、CSS-first 設定與效能飛躍

Tailwind CSS v4：重新定義原子化 CSS

v4 不是漸進升級，而是架構重寫——新引擎（Oxide）帶來 10x 構建速度，CSS-first 設定取代 JS 設定。

維度	v3	v4
引擎	PostCSS 外掛	Rust 引擎 (Oxide)
設定	`tailwind.config.js`	CSS `@theme` 指令
內容檢測	`content` 陣列	自動檢測
構建速度	基準	10x+
容器查詢	外掛	原生支援
3D 變換	外掛	原生支援

一、新引擎：Oxide

效能對比

操作	v3	v4	提升
全量構建 (1000+ 工具類)	~500ms	~50ms	10x
增量 HMR	~50ms	~5ms	10x
大型專案 (500+ 元件)	~2s	~200ms	10x

Oxide 使用 Rust 編寫，透過 Wasm 或原生模組整合到構建工具中。

二、CSS-first 設定

v3：JS 設定檔

// tailwind.config.js
module.exports = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        brand: '#3b82f6',
      },
      fontFamily: {
        sans: ['Inter', 'sans-serif'],
      },
    },
  },
  plugins: [require('@tailwindcss/typography')],
};

v4：CSS 設定

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

@theme {
  --color-brand: #3b82f6;
  --font-sans: "Inter", sans-serif;
  --breakpoint-xs: 475px;
  --spacing-18: 4.5rem;
}

優勢：

設定即 CSS，IDE 原生支援
無需 JS 執行時
更容易與設計系統對齊

自訂工具類

@theme {
  --animate-fade-in: fade-in 0.3s ease-out;
}

@keyframes fade-in {
  from { opacity: 0; transform: translateY(-10px); }
  to { opacity: 1; transform: translateY(0); }
}

<div class="animate-fade-in">淡入效果</div>

三、自動內容檢測

v4 不再需要手動設定 content 陣列，自動從專案結構推斷：

框架	檢測方式
Next.js	自動掃描 `app/`、`src/`
Vite	自動掃描 `src/`
Nuxt	自動掃描 `components/`、`pages/`
通用	自動掃描專案根目錄

如需排除路徑：

@import "tailwindcss" source("../src");
/* 或排除 */
@import "tailwindcss" source("../src") not("../src/generated");

四、原生容器查詢支援

v3 需要外掛

plugins: [require('@tailwindcss-container-queries')]
// <div class="md:max-w-sm"> → @container

v4 原生支援

<div class="@container">
  <div class="@md:flex-row flex-col">
    容器寬度 >= md 時水平佈局
  </div>
</div>

@theme {
  --container-md: 448px;
}

容器查詢類	含義
`@container`	定義容器
`@sm:flex-row`	容器 >= sm 時 flex-row
`@md:grid-cols-2`	容器 >= md 時兩列
`@lg:hidden`	容器 >= lg 時隱藏

五、3D 變換原生支援

<div class="rotate-x-45 rotate-y-30 rotate-z-15
            perspective-500 translate-z-10
            scale-3d scale-x-110 scale-y-90">
  3D 變換元素
</div>

類名	CSS 屬性
`rotate-x-45`	`rotateX(45deg)`
`rotate-y-30`	`rotateY(30deg)`
`rotate-z-15`	`rotateZ(15deg)`
`perspective-500`	`perspective(500px)`
`translate-z-10`	`translateZ(10px)`
`scale-3d`	`scale3d()`
`backface-hidden`	`backface-visibility: hidden`

六、遷移步驟

步驟一：升級依賴

npm install tailwindcss@next @tailwindcss/postcss@next

步驟二：更新 PostCSS 設定

// postcss.config.js
module.exports = {
  plugins: {
    '@tailwindcss/postcss': {},  // 替代 'tailwindcss'
  },
};

步驟三：遷移設定檔

/* app.css - 新設定 */
@import "tailwindcss";

/* 遷移 v3 的 theme.extend */
@theme {
  /* colors */
  --color-primary: #3b82f6;
  --color-secondary: #10b981;

  /* fontFamily */
  --font-sans: "Inter", "system-ui", sans-serif;
  --font-mono: "JetBrains Mono", monospace;

  /* spacing */
  --spacing-18: 4.5rem;

  /* breakpoints */
  --breakpoint-xs: 475px;
  --breakpoint-3xl: 1920px;
}

步驟四：處理 Breaking Changes

v3 寫法	v4 寫法	說明
`bg-opacity-50`	`bg-blue-500/50`	透明度修飾符
`overflow-ellipsis`	`text-ellipsis`	更名
`shadow-outline`	自訂	已移除

步驟五：移除不再需要的外掛

外掛	v4 替代
`@tailwindcss/container-queries`	原生支援
`@tailwindcss/3d`	原生支援
`@tailwindcss/line-clamp`	原生支援 (`line-clamp-3`)

七、Vite 整合

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';

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

不再需要 PostCSS 中介層——Vite 外掛直接整合，速度更快。

八、常見遷移陷阱

1. 自訂顏色不生效

/* 錯誤：缺少 --color- 前綴 */
@theme {
  --brand: #3b82f6;  /* 不會生成 text-brand, bg-brand */
}

/* 正確 */
@theme {
  --color-brand: #3b82f6;  /* 生成 text-brand, bg-brand, border-brand */
}

2. @apply 行為變化

/* v3: @apply 可以使用任意工具類 */
/* v4: @apply 僅支援靜態工具類，不支援動態值 */

.button {
  @apply bg-blue-500 text-white;  /* ✅ */
  @apply bg-[#123456];            /* ❌ 改用直接寫 CSS */
}

3. 前綴模式變化

/* v3: prefix 在 JS 設定中 */
/* v4: prefix 在 CSS 中 */
@import "tailwindcss" prefix(tw);
/* 生成 tw-flex, tw-text-lg 等 */

九、推薦遷移策略

新專案直接用 v4：零遷移成本
現有專案漸進遷移：v3 和 v4 可共存於不同入口
先遷移設定：將 JS 設定轉為 CSS @theme
再處理 Breaking Changes：使用官方 codemod
最後移除外掛：替換為原生功能

# 官方 codemod
npx @tailwindcss/upgrade@next