升級指南

Tailwind CSS v4.0 是該框架的一個新的主要版本，因此雖然我們已盡力減少破壞性變更，但仍有一些更新是必要的。本指南概述了將您的專案從 v3 升級到 v4 所需的所有步驟。

為了簡化流程，我們開發了一個遷移工具，可以在典型專案中自動處理大部分變更。

使用升級工具

如果您想嘗試將專案從 v3 升級到 v4，您可以使用我們的升級工具來完成絕大部分繁重的工作

$ npx @tailwindcss/upgrade@next

對於大多數專案，升級工具將自動化整個遷移流程，包括更新您的依賴項、將您的設定檔遷移到 CSS，以及處理對您的範本檔案的任何變更。

升級工具需要 Node.js 20 或更高版本，因此請確保您的環境在執行前已更新。

我們建議在新分支中執行升級工具，然後仔細檢閱差異並在瀏覽器中測試您的專案，以確保所有變更都正確無誤。在複雜的專案中，您可能需要手動調整一些內容，但無論如何，該工具都會為您節省大量時間。

最好也檢查一下 v4 中的所有重大變更，並充分了解已變更的內容，以防萬一您需要在專案中更新其他升級工具無法捕獲的內容。

手動升級

使用 PostCSS

在 v3 中，tailwindcss 套件是 PostCSS 外掛程式，但在 v4 中，PostCSS 外掛程式位於專用的 @tailwindcss/postcss 套件中。

此外，在 v4 中，匯入和供應商前綴現在會自動為您處理，因此如果您的專案中有 postcss-import 和 autoprefixer，您可以將其移除

export default {  plugins: {    "postcss-import": {},    tailwindcss: {},    autoprefixer: {},    "@tailwindcss/postcss": {},  },};

使用 Vite

如果您使用 Vite，我們建議您從 PostCSS 外掛程式遷移到我們新的專用 Vite 外掛程式，以獲得更佳的效能和最佳的開發人員體驗

import { defineConfig } from "vite";import tailwindcss from "@tailwindcss/vite";export default defineConfig({  plugins: [    tailwindcss(),  ],});

使用 Tailwind CLI

在 v4 中，Tailwind CLI 存在於專用的 @tailwindcss/cli 套件中。請更新您的所有建置命令以改用新的套件

npx tailwindcss -i input.css -o output.cssnpx @tailwindcss/cli -i input.css -o output.css

與 v3 的變更

以下是 Tailwind CSS v4.0 中所有重大變更的完整列表。

我們的升級工具將會自動處理大多數這些變更，因此我們強烈建議您盡可能使用它。

已移除 @tailwind 指令

在 v4 中，您使用一般的 CSS @import 語句匯入 Tailwind，而不是使用您在 v3 中使用的 @tailwind 指令

@tailwind base;@tailwind components;@tailwind utilities;@import "tailwindcss";

已移除已棄用的公用程式

我們已移除 v3 中棄用且已多年未記錄的任何公用程式。以下是已移除的內容列表以及現代替代方案

已重新命名的公用程式

我們已在 v4 中重新命名以下公用程式，使其更一致且更可預測

已更新陰影、半徑和模糊比例

我們已重新命名預設的陰影、半徑和模糊比例，以確保每個公用程式都有一個命名值。「裸」版本仍然適用於向後相容性，但除非更新為各自的 <utility>-xs 版本，否則 <utility>-sm 公用程式看起來會有所不同。

若要為這些變更更新您的專案，請將所有 v3 公用程式取代為 v4 版本

<input class="shadow-sm" /><input class="shadow-xs" /><input class="shadow" /><input class="shadow-sm" />

已重新命名的 outline 公用程式

先前的 outline-none 公用程式實際上並未設定 outline-style: none，而是設定一個隱形的外框，出於輔助功能的考量，在強制色彩模式下仍會顯示。

為了讓這點更清楚，我們已將此公用程式重新命名為 outline-hidden，並新增一個新的 outline-none 公用程式，該公用程式實際上會設定 outline-style: none。

若要為此變更更新您的專案，請將任何 outline-none 的用法取代為 outline-hidden

<input class="focus:outline-none" /><input class="focus:outline-hidden" />

預設 ring 寬度變更

在 v3 中，ring 公用程式會新增一個 3px 的 ring。我們在 v4 中已將其變更為 1px，使其與邊框和外框一致。

若要為此變更更新您的專案，請將任何 ring 的用法取代為 ring-3

<input class="ring ring-blue-500" /><input class="ring-3 ring-blue-500" />

容器配置

在 v3 中，container 公用程式具有數個配置選項，例如 center 和 padding，這些選項在 v4 中不再存在。

若要在 v4 中自訂 container 公用程式，請使用 @utility 指令擴充它

@utility container {  margin-inline: auto;  padding-inline: 2rem;}

Preflight 變更

我們已在 v4 的 Preflight 中對基本樣式進行了一些小變更

新的預設邊框顏色

在 v3 中，邊框預設會使用您設定的 gray-200 顏色。我們已在 v4 中將其更新為僅為 currentColor，這與所有瀏覽器的預設行為相符。

若要為此變更更新您的專案，請確保您在使用 border 公用程式的任何位置都使用邊框顏色公用程式，或將以下 CSS 行新增至您的專案以保留 v3 行為

@layer base {  *,  ::after,  ::before,  ::backdrop,  ::file-selector-button {    border-color: var(--color-gray-200, currentColor);  }}

新的預設預留位置顏色

在 v3 中，預留位置文字預設會使用您設定的 gray-400 顏色。我們已在 v4 中將其簡化為僅使用 50% 不透明度的目前文字顏色。

您可能甚至不會注意到此變更（它甚至可能使您的專案看起來更好），但如果您想要保留 v3 行為，請將此 CSS 新增至您的專案

@layer base {  input::placeholder,  textarea::placeholder {    color: theme(--color-gray-400);  }}

新增自訂公用程式

在 v3 中，您在 @layer utilities 中定義的任何自訂類別都會被 Tailwind 視為真正的公用程式類別，並會自動使用 hover、focus 或 lg 等變體。

在 v4 中，我們使用原生階層式圖層，並且不再劫持 @layer at-rule，因此我們引入 @utility API 作為替代方案

@layer utilities {  .tab-4 {    tab-size: 4;  }}@utility tab-4 {  tab-size: 4;}

在新增自訂公用程式文件中了解更多關於註冊自訂公用程式的資訊。

變體堆疊順序

在 v3 中，堆疊的變體是從右到左套用，但在 v4 中，我們已將它們更新為從左到右套用，使其更像 CSS 語法。

若要為此變更更新您的專案，請反轉您專案中任何順序敏感的堆疊變體的順序

<ul class="py-4 first:*:pt-0 last:*:pb-0"><ul class="py-4 *:first:pt-0 *:last:pb-0">  <li>One</li>  <li>Two</li>  <li>Three</li></ul>

如果有的話，您可能只有極少數這些變體 — 直接子變體 (*) 和任何排版外掛程式變體 (prose-headings) 是您最可能使用的變體，即使如此，也只有在您將它們與其他變體堆疊時才會使用。

任意值中的變數

在 v3 中，您可以使用 CSS 變數作為任意值而無需 var()，但最近對 CSS 的更新意味著這通常會造成含糊不清，因此我們已在 v4 中變更了此語法，改為使用括號而不是方括號。

若要為此變更更新您的專案，請將舊變數簡寫語法的用法取代為新的變數簡寫語法

<div class="bg-[--brand-color]"></div><div class="bg-(--brand-color)"></div>

行動裝置上的 hover 樣式

在 v4 中，我們已更新 hover 變體，使其僅在主要輸入裝置支援 hover 時才套用

@media (hover: hover) {  .hover\:underline:hover {    text-decoration: underline;  }}

如果您以一種依賴觸控裝置在點擊時觸發 hover 的方式建置您的網站，這可能會造成問題。如果這對您來說是個問題，您可以使用您自己的變體來覆寫 hover 變體，該變體會使用舊的實作方式

@custom-variant hover (&:hover);

不過，我們通常建議將 hover 功能視為增強功能，而不是依賴它來使您的網站運作，因為觸控裝置實際上沒有 hover 的能力。

停用核心外掛程式

在 v3 中，您可以使用 corePlugins 選項來完全停用框架中的某些公用程式。v4 中不再支援此功能。

使用 theme() 函式

由於 v4 包含所有主題值的 CSS 變數，我們建議您盡可能使用這些變數，而不是 theme() 函式

.my-class {  background-color: theme(colors.red.500);  background-color: var(--color-red-500);}

對於您仍然需要使用 theme() 函式的情況（例如在 CSS 變數不受支援的媒體查詢中），您應該使用 CSS 變數名稱，而不是舊的點符號

@media (width >= theme(screens.xl)) {@media (width >= theme(--breakpoint-xl)) {  /* ... */}

使用 JavaScript 設定檔

為了向後相容性，仍然支援 JavaScript 設定檔，但在 v4 中不再自動偵測到它們。

如果您仍然需要使用 JavaScript 設定檔，您可以使用 @config 指令明確載入它

@config "../../tailwind.config.js";

JavaScript 中的主題值

在 v3 中，我們匯出了一個 resolveConfig 函式，您可以使用該函式將您基於 JavaScript 的設定轉換為一個平面物件，您可以在其他 JavaScript 中使用。

我們已在 v4 中將其移除，希望人們可以直接使用我們產生的 CSS 變數，這更簡單，並且會顯著減少您的套件大小。

例如，用於 React 的熱門 Motion 函式庫可讓您動畫化 CSS 變數值的來回轉換。

<motion.div animate={{ backgroundColor: "var(--color-blue-500)" }} />

如果您需要在 JS 中存取已解析的 CSS 變數值，您可以使用 getComputedStyle 來取得文件根目錄上主題變數的值。

let styles = getComputedStyle(document.documentElement);let shadow = styles.getPropertyValue("--shadow-xl");