安裝 Tailwind CSS

從 CDN 快速試用到完整的 npm 安裝，選擇最適合你專案的方式。

方法一：Play CDN（快速試用）

如果只是想快速試用 Tailwind CSS，可以直接在 HTML 中引入 Play CDN。這個方式僅適合開發測試，不建議用於生產環境。 Play CDN 會在瀏覽器端即時掃描 DOM 並動態產生 CSS，雖然方便，但頁面初次載入會有短暫延遲，且無法使用部分進階功能。 

<!DOCTYPE html>
<html lang="zh-Hant">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <script src="https://cdn.tailwindcss.com"></script>
</head>
<body>
  <h1 class="text-3xl font-bold text-blue-500">Hello, Tailwind!</h1>
</body>
</html>
Play CDN 也支援透過 tailwind.config 物件在 script 標籤中直接設定主題擴充，適合快速原型開發時驗證設計方向。

方法二：npm + PostCSS（推薦）

這是最通用的安裝方式，適合所有使用 npm 的專案。PostCSS 作為 CSS 處理管線的核心，讓 Tailwind 能在建置時掃描你的模板並生成最小化的 CSS 輸出。

# 1. 初始化專案（若尚未建立）
npm init -y

# 2. 安裝 Tailwind CSS 及相關套件
npm install -D tailwindcss postcss autoprefixer

# 3. 生成設定檔
npx tailwindcss init -p

接著編輯 tailwind.config.js，設定 content 掃描路徑：

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{html,js,ts,jsx,tsx}",
    "./index.html",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

建立主要 CSS 檔案 src/input.css：

@tailwind base;
@tailwind components;
@tailwind utilities;

在 package.json 加入建置指令：

{
  "scripts": {
    "build": "tailwindcss -i ./src/input.css -o ./dist/output.css",
    "dev": "tailwindcss -i ./src/input.css -o ./dist/output.css --watch"
  }
}

方法三：搭配 Vite

Vite 是目前最流行的前端建置工具之一，與 Tailwind 整合非常順暢。Vite 的原生 ESM 開發伺服器搭配 HMR，讓樣式修改幾乎即時反映在瀏覽器中，大幅提升開發體驗。

# 建立 Vite 專案
npm create vite@latest my-project -- --template vanilla

cd my-project

# 安裝 Tailwind CSS
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
修改 tailwind.config.js 的 content 為：
content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"]

在 src/style.css 加入三行 Tailwind 指令，再執行 npm run dev 即可開始開發。若使用 React 或 Vue 模板，安裝步驟完全相同，只需依框架調整 content 的副檔名對應即可。

方法四：搭配 Next.js

Next.js 官方腳手架可自動設定 Tailwind CSS，並與 App Router 及 Server Components 完美相容。Next.js 13+ 預設使用 app/ 目錄，Tailwind 的掃描路徑也需對應調整。

# 建立 Next.js 專案（選擇 Tailwind CSS 選項）
npx create-next-app@latest my-app

# 或在現有 Next.js 專案中加入
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

在 app/globals.css 加入 Tailwind 指令後，Next.js 會自動處理其餘設定。若專案同時使用 pages/ 與 app/ 目錄，記得在 content 中同時涵蓋兩個路徑。

// next.js 專案的 tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./components/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: { extend: {} },
  plugins: [],
}

方法五：搭配 Laravel Mix

若你的後端是 Laravel，可以透過 Laravel Mix（基於 Webpack）整合 Tailwind CSS。Laravel 8+ 專案已內建 Mix，只需額外安裝 Tailwind 相關套件即可。此方案特別適合後端工程師在既有 Laravel 專案中快速導入 Tailwind，無需另行設定獨立的前端建置流程。

# 在 Laravel 專案根目錄執行
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init

編輯 webpack.mix.js，加入 PostCSS 管線：

const mix = require('laravel-mix');

mix.js('resources/js/app.js', 'public/js')
   .postCss('resources/css/app.css', 'public/css', [
     require('tailwindcss'),
     require('autoprefixer'),
   ]);

在 resources/css/app.css 加入 Tailwind 指令：

@tailwind base;
@tailwind components;
@tailwind utilities;

設定 tailwind.config.js 的 content 涵蓋 Blade 模板與 Vue 元件：

module.exports = {
  content: [
    "./resources/**/*.blade.php",
    "./resources/**/*.js",
    "./resources/**/*.vue",
  ],
  theme: { extend: {} },
  plugins: [],
}

最後執行 npm run dev（開發）或 npm run prod（生產）即可。Laravel Mix 會自動呼叫 PostCSS 並輸出最終 CSS 至 public/css/app.css。若專案有 Livewire 元件，也需在 content 中加入 ./app/Http/Livewire/**/*.php 路徑，確保動態渲染的 class 不被 purge 移除。

Laravel 9+ 推薦改用 Vite（由 vite.config.js 驅動），官方已提供 laravel-vite-plugin，整合更為簡潔。Mix 方案仍適用於維護中的舊版 Laravel 專案。新開的 Laravel 10/11 專案建議直接採用 Vite 方案，享有更快的 HMR 與更小的建置體積。

設定檔深度說明

完整的 tailwind.config.js 結構，涵蓋常見的真實專案客製化需求。以下範例示範三個最重要的擴充維度：暗色模式策略、自訂字型堆疊，以及間距比例系統。

暗色模式（darkMode）

Tailwind 提供兩種暗色模式策略。'media' 會跟隨作業系統的系統偏好，無需額外 JavaScript；'class' 則由你手動在 <html> 加上 dark class 來切換，適合需要提供手動開關的網站。 

module.exports = {
  // 跟隨系統偏好（prefers-color-scheme）
  darkMode: 'media',

  // 手動控制：<html class="dark">
  // darkMode: 'class',

  theme: {
    extend: {
      // 在 dark: 變體下使用自訂背景色
      colors: {
        surface: {
          light: '#ffffff',
          dark:  '#1a1f2e',
        },
      },
    },
  },
}
使用 'class' 策略時，搭配 localStorage 儲存使用者偏好，可在頁面重新整理後保留主題設定。參見 進階技巧 的動態主題切換章節。

自訂字型（fontFamily）

中文網站通常需要指定優先載入的中文字型，並在後方提供英文與系統備用字型。將字型宣告放在 extend 內可保留 Tailwind 預設字型堆疊，僅覆蓋 sans、serif 或 mono 分類。 

theme: {
  extend: {
    fontFamily: {
      // 中文優先字型堆疊
      sans: [
        'Noto Sans TC',
        'PingFang TC',
        'Microsoft JhengHei',
        'Inter',
        'ui-sans-serif',
        'sans-serif',
      ],
      // 技術文章用等寬字型
      mono: [
        'JetBrains Mono',
        'Fira Code',
        'ui-monospace',
        'monospace',
      ],
      // 標題專用展示字型
      display: [
        'Syne',
        'Inter',
        'sans-serif',
      ],
    },
  },
},

間距比例（spacing scale）

Tailwind 預設以 4px 為基準單位（1 = 4px）。若設計稿採用 8pt grid，可在 extend.spacing 補充常用的半格單位與大尺寸值，讓 class 名稱直接對應設計數值，減少換算錯誤。 

theme: {
  extend: {
    spacing: {
      // 半格補充（4.5rem = 72px）
      '18': '4.5rem',
      '22': '5.5rem',
      // 大版面專用
      '88':  '22rem',   // 352px
      '128': '32rem',   // 512px
      '144': '36rem',   // 576px
      // 側邊欄寬度語意化命名
      'sidebar': '16rem',
      'sidebar-lg': '20rem',
    },
    // 自訂斷點（配合設計稿）
    screens: {
      'xs':  '480px',
      '3xl': '1920px',
    },
    // 自訂陰影層次
    boxShadow: {
      'card':  '0 2px 8px rgba(0,0,0,.08), 0 0 1px rgba(0,0,0,.06)',
      'modal': '0 20px 60px rgba(0,0,0,.3)',
    },
    // 滑入動畫
    keyframes: {
      'slide-up': {
        '0%':   { transform: 'translateY(10px)', opacity: '0' },
        '100%': { transform: 'translateY(0)',    opacity: '1' },
      },
    },
    animation: {
      'slide-up': 'slide-up 0.2s ease-out',
    },
  },
},
plugins: [
  require('@tailwindcss/forms'),        // 表單樣式重設
  require('@tailwindcss/typography'),    // Markdown 文章排版（prose）
  require('@tailwindcss/line-clamp'),   // 多行文字截斷
  require('@tailwindcss/aspect-ratio'), // 寬高比輔助
],
建議：將品牌色彩、字型與斷點集中在 extend 中定義，以便與設計師共用設計令牌（Design Tokens）。配合 CSS 變數 可進一步支援動態主題切換。

常見安裝問題

Q1：執行 npm run dev 後 CSS 沒有輸出，或只有空白檔案？

最常見的原因是 content 路徑設定錯誤，導致 Tailwind 掃描不到任何 class，進而輸出空白 CSS。請確認路徑 glob 是否正確覆蓋你的模板檔案，並注意路徑是相對於 tailwind.config.js 所在位置。 

# 常見錯誤：路徑不含副檔名或目錄層級不對
content: ["./src/*.html"]        // 只掃描 src 根目錄

# 正確寫法：使用 ** 遞迴掃描子目錄
content: ["./src/**/*.{html,js,jsx,ts,tsx}"]

Q2：生產環境建置後，某些動態 class（如 text-red-500）被移除了？

Tailwind 採用靜態掃描方式偵測使用的 class。若你的 class 是用字串拼接動態產生（例如 `text-${color}-500`），Tailwind 無法識別，建置時會將其移除。解決方案是使用 safelist 強制保留這些 class： 

// tailwind.config.js
module.exports = {
  safelist: [
    'text-red-500', 'text-green-500', 'text-blue-500',
    // 或使用 pattern 批量保留
    { pattern: /^text-(red|green|blue)-(400|500|600)$/ },
  ],
  // ...
}

Q3：安裝後 VS Code 沒有出現 Tailwind class 的自動補全？

請確認已安裝 Tailwind CSS IntelliSense 擴充套件（發行者為 Tailwind Labs）。若已安裝仍無效，常見原因包括：工作區根目錄缺少 tailwind.config.js、設定檔語法錯誤，或 VS Code 需要重新載入視窗。可嘗試按 Ctrl+Shift+P 執行「Developer: Reload Window」。此外，若專案為 monorepo 架構，需在 VS Code 的 settings.json 中設定 "tailwindCSS.experimental.configFile" 指向正確的設定檔路徑。

Q4：PostCSS 回報 Cannot find module 'tailwindcss' 錯誤？

這通常是套件安裝在全域而非本地，或 node_modules 損壞所致。請依序執行以下步驟： 

# 刪除 node_modules 與 lock 檔後重新安裝
rm -rf node_modules package-lock.json

npm install

# 確認 tailwindcss 已在 devDependencies 中
npm list tailwindcss
若使用 pnpm 或 yarn，請確認 postcss.config.js 的 require 路徑能正確解析。部分 monorepo 設定需在 postcss.config.js 中使用絕對路徑或 require.resolve('tailwindcss')。
Play CDN 也支援透過 tailwind.config 物件在 script 標籤中直接設定主題擴充，適合快速原型開發時驗證設計方向。

方法二：npm + PostCSS（推薦）

這是最通用的安裝方式，適合所有使用 npm 的專案。PostCSS 作為 CSS 處理管線的核心，讓 Tailwind 能在建置時掃描你的模板並生成最小化的 CSS 輸出。

# 1. 初始化專案（若尚未建立）
npm init -y

# 2. 安裝 Tailwind CSS 及相關套件
npm install -D tailwindcss postcss autoprefixer

# 3. 生成設定檔
npx tailwindcss init -p

接著編輯 tailwind.config.js，設定 content 掃描路徑：

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{html,js,ts,jsx,tsx}",
    "./index.html",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

建立主要 CSS 檔案 src/input.css：

@tailwind base;
@tailwind components;
@tailwind utilities;

在 package.json 加入建置指令：

{
  "scripts": {
    "build": "tailwindcss -i ./src/input.css -o ./dist/output.css",
    "dev": "tailwindcss -i ./src/input.css -o ./dist/output.css --watch"
  }
}

方法三：搭配 Vite

Vite 是目前最流行的前端建置工具之一，與 Tailwind 整合非常順暢。Vite 的原生 ESM 開發伺服器搭配 HMR，讓樣式修改幾乎即時反映在瀏覽器中，大幅提升開發體驗。

# 建立 Vite 專案
npm create vite@latest my-project -- --template vanilla

cd my-project

# 安裝 Tailwind CSS
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
修改 tailwind.config.js 的 content 為：
content: ["./index.html", "./src/**/*.{js,ts,jsx,tsx}"]

在 src/style.css 加入三行 Tailwind 指令，再執行 npm run dev 即可開始開發。若使用 React 或 Vue 模板，安裝步驟完全相同，只需依框架調整 content 的副檔名對應即可。

方法四：搭配 Next.js

Next.js 官方腳手架可自動設定 Tailwind CSS，並與 App Router 及 Server Components 完美相容。Next.js 13+ 預設使用 app/ 目錄，Tailwind 的掃描路徑也需對應調整。

# 建立 Next.js 專案（選擇 Tailwind CSS 選項）
npx create-next-app@latest my-app

# 或在現有 Next.js 專案中加入
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

在 app/globals.css 加入 Tailwind 指令後，Next.js 會自動處理其餘設定。若專案同時使用 pages/ 與 app/ 目錄，記得在 content 中同時涵蓋兩個路徑。

// next.js 專案的 tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./components/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: { extend: {} },
  plugins: [],
}

方法五：搭配 Laravel Mix

若你的後端是 Laravel，可以透過 Laravel Mix（基於 Webpack）整合 Tailwind CSS。Laravel 8+ 專案已內建 Mix，只需額外安裝 Tailwind 相關套件即可。此方案特別適合後端工程師在既有 Laravel 專案中快速導入 Tailwind，無需另行設定獨立的前端建置流程。

# 在 Laravel 專案根目錄執行
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init

編輯 webpack.mix.js，加入 PostCSS 管線：

const mix = require('laravel-mix');

mix.js('resources/js/app.js', 'public/js')
   .postCss('resources/css/app.css', 'public/css', [
     require('tailwindcss'),
     require('autoprefixer'),
   ]);

在 resources/css/app.css 加入 Tailwind 指令：

@tailwind base;
@tailwind components;
@tailwind utilities;

設定 tailwind.config.js 的 content 涵蓋 Blade 模板與 Vue 元件：

module.exports = {
  content: [
    "./resources/**/*.blade.php",
    "./resources/**/*.js",
    "./resources/**/*.vue",
  ],
  theme: { extend: {} },
  plugins: [],
}

最後執行 npm run dev（開發）或 npm run prod（生產）即可。Laravel Mix 會自動呼叫 PostCSS 並輸出最終 CSS 至 public/css/app.css。若專案有 Livewire 元件，也需在 content 中加入 ./app/Http/Livewire/**/*.php 路徑，確保動態渲染的 class 不被 purge 移除。

Laravel 9+ 推薦改用 Vite（由 vite.config.js 驅動），官方已提供 laravel-vite-plugin，整合更為簡潔。Mix 方案仍適用於維護中的舊版 Laravel 專案。新開的 Laravel 10/11 專案建議直接採用 Vite 方案，享有更快的 HMR 與更小的建置體積。

設定檔深度說明

完整的 tailwind.config.js 結構，涵蓋常見的真實專案客製化需求。以下範例示範三個最重要的擴充維度：暗色模式策略、自訂字型堆疊，以及間距比例系統。

暗色模式（darkMode）

Tailwind 提供兩種暗色模式策略。'media' 會跟隨作業系統的系統偏好，無需額外 JavaScript；'class' 則由你手動在 <html> 加上 dark class 來切換，適合需要提供手動開關的網站。 

module.exports = {
  // 跟隨系統偏好（prefers-color-scheme）
  darkMode: 'media',

  // 手動控制：<html class="dark">
  // darkMode: 'class',

  theme: {
    extend: {
      // 在 dark: 變體下使用自訂背景色
      colors: {
        surface: {
          light: '#ffffff',
          dark:  '#1a1f2e',
        },
      },
    },
  },
}
使用 'class' 策略時，搭配 localStorage 儲存使用者偏好，可在頁面重新整理後保留主題設定。參見 進階技巧 的動態主題切換章節。

自訂字型（fontFamily）

中文網站通常需要指定優先載入的中文字型，並在後方提供英文與系統備用字型。將字型宣告放在 extend 內可保留 Tailwind 預設字型堆疊，僅覆蓋 sans、serif 或 mono 分類。 

theme: {
  extend: {
    fontFamily: {
      // 中文優先字型堆疊
      sans: [
        'Noto Sans TC',
        'PingFang TC',
        'Microsoft JhengHei',
        'Inter',
        'ui-sans-serif',
        'sans-serif',
      ],
      // 技術文章用等寬字型
      mono: [
        'JetBrains Mono',
        'Fira Code',
        'ui-monospace',
        'monospace',
      ],
      // 標題專用展示字型
      display: [
        'Syne',
        'Inter',
        'sans-serif',
      ],
    },
  },
},

間距比例（spacing scale）

Tailwind 預設以 4px 為基準單位（1 = 4px）。若設計稿採用 8pt grid，可在 extend.spacing 補充常用的半格單位與大尺寸值，讓 class 名稱直接對應設計數值，減少換算錯誤。 

theme: {
  extend: {
    spacing: {
      // 半格補充（4.5rem = 72px）
      '18': '4.5rem',
      '22': '5.5rem',
      // 大版面專用
      '88':  '22rem',   // 352px
      '128': '32rem',   // 512px
      '144': '36rem',   // 576px
      // 側邊欄寬度語意化命名
      'sidebar': '16rem',
      'sidebar-lg': '20rem',
    },
    // 自訂斷點（配合設計稿）
    screens: {
      'xs':  '480px',
      '3xl': '1920px',
    },
    // 自訂陰影層次
    boxShadow: {
      'card':  '0 2px 8px rgba(0,0,0,.08), 0 0 1px rgba(0,0,0,.06)',
      'modal': '0 20px 60px rgba(0,0,0,.3)',
    },
    // 滑入動畫
    keyframes: {
      'slide-up': {
        '0%':   { transform: 'translateY(10px)', opacity: '0' },
        '100%': { transform: 'translateY(0)',    opacity: '1' },
      },
    },
    animation: {
      'slide-up': 'slide-up 0.2s ease-out',
    },
  },
},
plugins: [
  require('@tailwindcss/forms'),        // 表單樣式重設
  require('@tailwindcss/typography'),    // Markdown 文章排版（prose）
  require('@tailwindcss/line-clamp'),   // 多行文字截斷
  require('@tailwindcss/aspect-ratio'), // 寬高比輔助
],
建議：將品牌色彩、字型與斷點集中在 extend 中定義，以便與設計師共用設計令牌（Design Tokens）。配合 CSS 變數 可進一步支援動態主題切換。

常見安裝問題

Q1：執行 npm run dev 後 CSS 沒有輸出，或只有空白檔案？

最常見的原因是 content 路徑設定錯誤，導致 Tailwind 掃描不到任何 class，進而輸出空白 CSS。請確認路徑 glob 是否正確覆蓋你的模板檔案，並注意路徑是相對於 tailwind.config.js 所在位置。 

# 常見錯誤：路徑不含副檔名或目錄層級不對
content: ["./src/*.html"]        // 只掃描 src 根目錄

# 正確寫法：使用 ** 遞迴掃描子目錄
content: ["./src/**/*.{html,js,jsx,ts,tsx}"]

Q2：生產環境建置後，某些動態 class（如 text-red-500）被移除了？

Tailwind 採用靜態掃描方式偵測使用的 class。若你的 class 是用字串拼接動態產生（例如 `text-${color}-500`），Tailwind 無法識別，建置時會將其移除。解決方案是使用 safelist 強制保留這些 class： 

// tailwind.config.js
module.exports = {
  safelist: [
    'text-red-500', 'text-green-500', 'text-blue-500',
    // 或使用 pattern 批量保留
    { pattern: /^text-(red|green|blue)-(400|500|600)$/ },
  ],
  // ...
}

Q3：安裝後 VS Code 沒有出現 Tailwind class 的自動補全？

請確認已安裝 Tailwind CSS IntelliSense 擴充套件（發行者為 Tailwind Labs）。若已安裝仍無效，常見原因包括：工作區根目錄缺少 tailwind.config.js、設定檔語法錯誤，或 VS Code 需要重新載入視窗。可嘗試按 Ctrl+Shift+P 執行「Developer: Reload Window」。此外，若專案為 monorepo 架構，需在 VS Code 的 settings.json 中設定 "tailwindCSS.experimental.configFile" 指向正確的設定檔路徑。

Q4：PostCSS 回報 Cannot find module 'tailwindcss' 錯誤？

這通常是套件安裝在全域而非本地，或 node_modules 損壞所致。請依序執行以下步驟： 

# 刪除 node_modules 與 lock 檔後重新安裝
rm -rf node_modules package-lock.json

npm install

# 確認 tailwindcss 已在 devDependencies 中
npm list tailwindcss
若使用 pnpm 或 yarn，請確認 postcss.config.js 的 require 路徑能正確解析。部分 monorepo 設定需在 postcss.config.js 中使用絕對路徑或 require.resolve('tailwindcss')。