1. 核心概念(Core Concepts)
  2. 偵測原始檔中的類別(Detecting classes in source files)

核心概念(Core Concepts)

偵測原始檔中的類別(Detecting classes in source files)

了解和自訂 Tailwind 如何掃描你的原始檔。

概述(Overview)

Tailwind 的運作方式是掃描你的專案以尋找通用類別,然後根據你實際使用的類別產生所有必要的 CSS。

這確保你的 CSS 盡可能小,同時也是讓任意值等功能成為可能的原因。

如何偵測類別(How classes are detected)

Tailwind 將你所有的原始檔視為純文字,不會以任何方式嘗試實際解析你的檔案為程式碼。

相反,它只是根據 Tailwind 預期在類別名稱中出現的字元,在你的檔案中尋找任何可能是類別的標記:

JSX
export function Button({ color, children }) {  const colors = {    black: "bg-black text-white",    blue: "bg-blue-500 text-white",    white: "bg-white text-black",  };  return (    <button className={`${colors[color]} rounded-full px-2 py-1.5 font-sans text-sm/6 font-medium shadow`}>      {children}    </button>  );}

然後它會嘗試為所有這些標記產生 CSS,丟棄任何無法對應到框架已知通用類別的標記。

動態類別名稱(Dynamic class names)

由於 Tailwind 將你的原始檔作為純文字掃描,它無法理解你所使用的程式語言中的字串串接或插值。

不要動態建構類別名稱

HTML
<div class="text-{{ error ? 'red' : 'green' }}-600"></div>

在上面的範例中,字串 text-red-600text-green-600 不存在,所以 Tailwind 不會產生這些類別。

相反,請確保你使用的任何類別名稱都完整存在:

始終使用完整的類別名稱

HTML
<div class="{{ error ? 'text-red-600' : 'text-green-600' }}"></div>

如果你使用像 React 或 Vue 這樣的元件庫,這意味著你不應該使用 props 來動態建構類別:

不要使用 props 動態建構類別名稱

JSX
function Button({ color, children }) {  return <button className={`bg-${color}-600 hover:bg-${color}-500 ...`}>{children}</button>;}

相反,將 props 對應到在建構時可靜態偵測的完整類別名稱:

始終將 props 對應到靜態類別名稱

JSX
function Button({ color, children }) {  const colorVariants = {    blue: "bg-blue-600 hover:bg-blue-500",    red: "bg-red-600 hover:bg-red-500",  };  return <button className={`${colorVariants[color]} ...`}>{children}</button>;}

這還有一個額外的好處,例如讓你可以將不同的 prop 值對應到不同的色調:

JSX
function Button({ color, children }) {  const colorVariants = {    blue: "bg-blue-600 hover:bg-blue-500 text-white",    red: "bg-red-500 hover:bg-red-400 text-white",    yellow: "bg-yellow-300 hover:bg-yellow-400 text-black",  };  return <button className={`${colorVariants[color]} ...`}>{children}</button>;}

只要你始終在程式碼中使用完整的類別名稱,Tailwind 每次都會完美地產生所有的 CSS。

哪些檔案會被掃描(Which files are scanned)

Tailwind 會掃描專案中的每個檔案以尋找類別名稱,除了以下情況:

  • 在你的 .gitignore 檔案中的檔案
  • node_modules 目錄中的檔案
  • 二進制檔案,如圖片、影片或 zip 檔案
  • CSS 檔案
  • 常見的套件管理器鎖定檔案

如果你需要掃描 Tailwind 預設忽略的任何檔案,可以明確註冊這些來源。

明確註冊來源(Explicitly registering sources)

使用 @source 明確註冊相對於樣式表的來源路徑:

CSS
@import "tailwindcss";@source "../node_modules/@acmecorp/ui-lib";

當你需要掃描使用 Tailwind 建構的外部函式庫時,這特別有用,因為相依套件通常列在你的 .gitignore 檔案中,預設會被 Tailwind 忽略。

設定你的基礎路徑(Setting your base path)

預設情況下,Tailwind 在掃描類別名稱時使用當前工作目錄作為起始點。

若要明確設定來源偵測的基礎路徑,請在 CSS 中匯入 Tailwind 時使用 source() 函式:

CSS
@import "tailwindcss" source("../src");

在使用 monorepo 時這會很有用,因為你的建構命令是從 monorepo 的根目錄而不是每個專案的根目錄執行。

忽略特定路徑(Ignoring specific paths)

使用 @source not 在掃描類別名稱時忽略相對於樣式表的特定路徑:

CSS
@import "tailwindcss";@source not "../src/components/legacy";

當你的專案中有大型目錄且你知道它們不使用 Tailwind 類別時,這會很有用,例如舊版元件或第三方函式庫。

停用自動偵測(Disabling automatic detection)

如果你想明確註冊所有來源,請使用 source(none) 完全停用自動來源偵測:

CSS
@import "tailwindcss" source(none);@source "../admin";@source "../shared";

在有多個 Tailwind 樣式表的專案中,這會很有用,因為你希望確保每個樣式表只包含它所需要的類別。

安全清單特定通用類別(Safelisting specific utilities)

如果你需要確保 Tailwind 產生某些在你的內容檔案中不存在的類別名稱,請使用 @source inline() 強制產生它們:

CSS
@import "tailwindcss";@source inline("underline");
Generated CSS
.underline {  text-decoration-line: underline;}

安全清單變體(Safelisting variants)

你也可以使用 @source inline() 產生帶有變體的類別。例如,要產生帶有 hover 和 focus 變體的 underline 類別,請在來源輸入中新增 {hover:,focus:,}

CSS
@import "tailwindcss";@source inline("{hover:,focus:,}underline");
Generated CSS
.underline {  text-decoration-line: underline;}@media (hover: hover) {  .hover\:underline:hover {    text-decoration-line: underline;  }}@media (focus: focus) {  .focus\:underline:focus {    text-decoration-line: underline;  }}

使用範圍的安全清單(Safelisting with ranges)

來源輸入會進行大括號展開,因此你可以一次產生多個類別。例如,要產生所有帶有 hover 變體的紅色背景顏色,請使用範圍:

CSS
@import "tailwindcss";@source inline("{hover:,}bg-red-{50,{100..900..100},950}");
Generated CSS
.bg-red-50 {  background-color: var(--color-red-50);}.bg-red-100 {  background-color: var(--color-red-100);}.bg-red-200 {  background-color: var(--color-red-200);}/* ... */.bg-red-800 {  background-color: var(--color-red-800);}.bg-red-900 {  background-color: var(--color-red-900);}.bg-red-950 {  background-color: var(--color-red-950);}@media (hover: hover) {  .hover\:bg-red-50:hover {    background-color: var(--color-red-50);  }  /* ... */  .hover\:bg-red-950:hover {    background-color: var(--color-red-950);  }}

這會產生從 100 到 900 每次增量 100 的紅色背景顏色,以及 50 和 950 的第一個和最後一個色調。它還為每個類別新增 hover: 變體。

明確排除類別(Explicitly excluding classes)

使用 @source not inline() 防止特定類別被產生,即使它們在你的原始檔中被偵測到:

CSS
@import "tailwindcss";@source not inline("{hover:,focus:,}bg-red-{50,{100..900..100},950}");

這將明確排除紅色背景通用類別及其 hover 和 focus 變體,使它們不會被產生。

Copyright © 2026 Tailwind Labs Inc.·商標政策(Brand)