安裝 - Tailwind CSS

如果你要以 CDN 方式引入 Tailwind CSS，點我快速帶你到那邊去！

各框架的安裝教學

Tailwind CSS 的安裝過程可能會因為你所使用的框架 ( frameworks ) 或工具 ( tools ) 不同而有些微差異，所以這邊整合了在幾個熱門框架上及工具中安裝 Tailwind CSS 的方法。

如果在列表中沒看到你常用的工具也沒關係，是因為官方還在努力的開發新的教學手冊。但你別氣餒，你還可以馬上使用以 PostCSS 插件的方式來安裝 Tailwind CSS 的方法來進行安裝及設定。

以 PostCSS 插件的方式來安裝 Tailwind CSS

Tailwind CSS 需要 Node.js 版本在 12.13.0 以上

對多數實際的案例來說，我們建議以 PostCSS 插件的方式來安裝 Tailwind CSS，因為目前大部分框架都已經有內建 PostCSS 了，而且你可以也已經習慣使用 PostCSS，又或是可能現在專案裡就已經使用了像是 autoprefixer 這種 PostCSS 插件。

如果你還沒有了解過 PostCSS，或不知道它和 Sass或其他工具的差別，你可以看一下 PostCSS 預編譯器這篇的說明。

如果這對你來說太麻煩了，而且你也不想透過 PostCSS 來架設 Tailwind CSS 的話，你可以看看我們關於使用 Tailwind CLI 的說明。

用 npm 來安裝 Tailwind

對於大部分的專案以及想要用 Tailwind 客製化功能的人而言，會選擇透過 npm 來安裝 Tailwind 及其他必要的(依賴的)項目。

npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

為了解決 Tailwind 生成 CSS 時不自動添加供應商前綴 (vendor prefixes) 的情形，這裡推薦可以使用上面這行指令安裝 autoprefixer 來處理問題。

如果你的 Tailwind 是跟必須使用舊版 PostCSS 的工具做整合，很有可能會看到下面這個錯誤：

Error: PostCSS plugin tailwindcss requires PostCSS 8.

如果碰到上面這個情況，你需要改成安裝 PostCSS 7 的相容版本。

以 PostCSS 插件方式新增 Tailwind

把 tailwind 和 autoprefixer 增加到 PostCSS 的配置設定中。通常，你的專案目錄下會有一個叫 postcss.config.js 的檔案，但也有可能是 .postcssrc 格式的檔案，或者是以 postcss 金鑰的方式存在 package.json 檔案中。

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

如果在你的工具中還是找不到去哪裡配置 PostCSS 插件，那你可以參考一下你工具的文件說明，也可以善用Google搜尋去下關鍵字，如 「XXX軟體 postCSS 設定」、「XXX框架 postCSS 設定」 ，相信你很快就能找到答案了。

如果你已經有用過任何其它的 PostCSS 插件，你可以從這篇 PostCSS 預編譯器看到更多關於 Tailwind 去配合那些插件的最好方法。

產生 Tailwind 的配置檔 / 設定檔

如果想要客製化你的 Tailwind，在你安裝 tailwindcss 這個 npm 套件後，可以透過 Tailwind CLI 工具在你的專案裡產生一個配置檔。

npx tailwindcss init

這時候會產生一個預設值的配置檔 tailwind.config.js 在你的專案根目錄：

// tailwind.config.js 設定檔
module.exports = {
  purge: [],
  darkMode: false, // 也可以是 'media' 或 'class'
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

想要更詳細的去設定你的 Tailwind 的話，可以看一下配置

在 CSS 中引入 Tailwind

如果你還沒有 CSS 檔，那先建立一個，然後使用 @tailwind 這個指令來載入 Tailwind 的 base、components 和 utilities樣式：

/* ./你-css-的資料夾/styles.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

Tailwind 會根據你設計系統的設定，在建置的時候把那些指令替換成 CSS樣式。

如果你用的是 postcss-import ( 或另外使用它的工具，如 Webpacker for Rails )，請不要使用 @tailwind 指令，而是改用 import 的方式來避免你在引入自己的其它檔案時發生問題：

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

如果你使用的是像 React、Vue 之類的 JavaScript 框架，它們可以直接引入 CSS 檔到你的 JS ，你也可以忽略前面這個步驟，改成建立一個將這些指令全都寫進去的 CSS 檔，並在你的頁面中引入 tailwindcss/tailwind.css

// app.js
import "tailwindcss/tailwind.css"

建置你的 CSS

實際上要怎麼建造你的專案是取決於你使用的工具。你的框架可能有像是 npm run dev 這樣的指令來讓你的開發伺服器在背景開始編譯你的 CSS，你也可以自己執行 webpack，又或者你可以用 postcss-cli 然後執行像 postcss styles.css -o compiled.css 這樣的指令。

如果你已經很熟悉 PostCSS，那你應該知道要做些什麼了。但如果不熟悉，請去參考你所使用工具的文件。

如果要建置給生產環境，請檢查設定檔中的 purge 裡包含了你所有用到 Tailwindcss 的檔案，以確保能移除未用到的 class 而讓檔案大小能維持在最小。

  // tailwind.config.js
  module.exports = {
+   purge: [
+     './src/**/*.html',
+     './src/**/*.js',
+   ],
    darkMode: false, // 也可以是 'media' 或 'class'
    theme: {
      extend: {},
    },
    variants: {},
    plugins: [],
  }

想學習更多關於「用 tree-shaking 來移除未用到的樣式」從而達到最佳效能的話，參閱我們的優化生產模式這篇獨立指南。

如果你是使用舊版 PostCSS 作為整合 Tailwind 的工具，那你非常有可能在嘗試編譯 CSS 時看到這個錯誤：

Error: PostCSS plugin tailwindcss requires PostCSS 8.

如果遇到這個情況，你應該要改成使用我們專為 PostCSS 7 建置的相容版本。

使用 Tailwind CLI

Tailwind CSS 需要 Node.js 版本在 12.13.0 以上

如果你想要不與其他建置工具一起使用就能夠令 Tailwind 編譯你的 CSS，又或者是你不想配置 PostCSS 或安裝 Tailwind 為依賴套件，那麼你就可以直接透過 Tailwind CLI 工具來生成 CSS。

使用 npx 工具來產生一個完整編譯版的 Tailwind CSS 檔案： (npx 會隨著 npm 一起自動安裝)

npx tailwindcss -o tailwind.css

執行後會產生一個名為 tailwind.css 的檔案，內容是根據 Tailwind 的預設配置做為基底產生的，且會使用 autoprefixer 來自動地添加上所有必要的供應商前綴。

現在，你可以像任何其他的 CSS 檔 (stylesheet) 一樣，將檔案掛載到你的 HTML 頁面上：

  <!doctype html>
  <html>
  <head>
    <!-- ... -->
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+   <link href="/tailwind.css" rel="stylesheet">
  </head>
  <body>
    <!-- ... -->
  </body>
  </html>

監聽內容的變動

你可以在指令中加上 --watch 或是 -w 標籤來啟動你的監聽程序。它會在檔案有任何變化時馬上自動重新編譯你的 CSS：

npx tailwindcss -o tailwind.css --watch

使用客製化的 CSS 檔

如果你希望自訂的 CSS 樣式能隨著 Tailwind 的預設樣式一起編譯，請建立一個 CSS 檔案並且加上 @tailwind 來引入 Tailwind 的 base、components 以及 utilities 樣式：

/* ./src/tailwind.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .btn {
    @apply px-4 py-2 bg-blue-600 text-white rounded;
  }
}

接著，加入剛剛建立的檔案 (檔名包含路徑)，然後建置你的 CSS：

npx tailwindcss -i ./src/tailwind.css -o ./dist/tailwind.css

看看增加基底樣式、提取成元件以及增加新功能頁面來學習更多關於如何在 Tailwind 中自訂 CSS。

自訂配置

如果你想要自訂 Tailwind 產生的內容，請用 Tailwind CLI 工具來建立一個 tailwind.config.js 檔案：

npx tailwindcss init

這個過程將會在你的專案根目錄中建立一個最小化配置的 tailwind.config.js 檔案：

// tailwind.config.js
module.exports = {
  purge: [],
  darkMode: false, // 也可以是 'media' 或 'class'
  theme: {
    extend: {},
  },
  variants: {},
  plugins: [],
}

當你使用 Tailwind CLI 建構你的 CSS 時，這個檔案會被自動讀取：

npx tailwindcss -i ./src/tailwind.css -o ./dist/tailwind.css

如果你想讓你的配置檔換一個名字或者在別的資料夾，請在你編譯 CSS 時加上 -c 選項並附上新的檔案名稱及路徑：

npx tailwindcss -i ./src/tailwind.css -c ./.config/tailwind.config.js -o ./dist/tailwind.css

在配置頁面中，可學習到更多有關 Tailwind 的配置。

停用 Autoprefixer

一般來說，Tailwind CLI 工具會透過 Autoprefixer 來增加必要的供應商前綴。如果你已經有在你的建置流程中使用 Autoprefixer，那你可以使用 --no-autoprefixer 選項來停用 Tailwind CLI 工具中的 Autoprefixer。

npx tailwindcss --no-autoprefixer -o tailwind.css

使用自訂的 PostCSS 配置

如果你想要別的 PostCSS 插件能隨著 Tailwind 一起使用，你可以在專案根目錄建立一個 postcss.config.js 檔案，並且在檔案中增添額外的插件，那麼當你使用 --postcss 參數來編譯 CSS 時，Tailwind 就會在建置你的 CSS 時將它們引入：

npx tailwindcss --postcss -o tailwind.css

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-100vh-fix'),
  ]
}

一般來說，所有的插件都 只會在 Tailwind 生成完 CSS 後 才會運作，但如果你的插件需要搶先在 Tailwind 編譯之前執行，那就只要在你的插件列表中加入 tailwindcss，Tailwind CLI 將會偵測到，並且依照插件列表的順序執行：

// postcss.config.js
module.exports = {
  plugins: [
    require('postcss-import'),
    require('tailwindcss'),
    require('postcss-100vh-fix'),
  ]
}

如果你想要在產生 tailwind.config.js 時跟著自動產生基本款的 postcss.config.js，那你只要在指令中加上 --postcss 或 -p 標籤即可：

npx tailwindcss init --postcss

生產環境建置

想要為生產環境進行建置，請在你建置 CSS 時把 NODE_ENV=production 加在指令最前方：

NODE_ENV=production npx tailwindcss -i ./src/tailwind.css -o ./dist/tailwind.css

為確保獲得最佳的效能，Tailwind 將會移除未用到的 CSS 樣式。你可以參閱優化生產模式來獲得更多資訊。

你也可以用 --minify 標籤來透過 cssnano 來對你的 CSS 進行壓縮：

NODE_ENV=production npx tailwindcss -i ./src/tailwind.css -o ./dist/tailwind.css --minify

透過 CDN 方式引入Tailwind

在用 CDN 引入之前請注意，因為 Tailwind 有很多特色功能是必須要安裝才能使用的，如果要用CDN方式使用 Tailwind，需要稍微留意一下下面幾點：

如果想要 Tailwind 的完整功能，你應該要以 PostCSS 插件的方式來安裝 Tailwind CSS

如果想要快速的玩轉一下 Tailwind，或是想測試一下這個框架，你可以用 CDN 來取得最新的預設配置：

<link href="https://unpkg.com/tailwindcss@^2/dist/tailwind.min.css" rel="stylesheet">

請注意一下，CDN 版是很大的 ( 壓縮後 71.5kB, 原始大小 3020.9kB )。**但這不代表 Tailwind 建置之後還會是這種大小。**

但是如果用我們提供的最佳做法，可以把檔案大小壓在 10kB 以下。

入門 HTML 樣版

為了讓你的 Tailwind 樣式能夠如預期般正常運作，你會需要用 HTML5 doctype (檔案類型聲明) 以及引用響應式 viewport meta 標籤來確保能夠在所有裝置上處理響應式樣式。

<!doctype html>
<html>
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <link href="/path/to/tailwind.css" rel="stylesheet">
  <!-- ... -->
</head>
<body>
  <!-- ... -->
</body>
</html>

許多像是 Next.js、vue-cli 之類的前端框架都已經先把這部分處理及設定完了，所以根據你的建置內容而定，你也有可能不會需要設定這些。

PostCSS 7 的相容版本

隨著 v2.0 版本的到來，Tailwind CSS 改為依賴 PostCSS 8。而正因為 PostCSS 8 才問世幾個月之久，其他許多工具的生態系統都尚未更新，所以你很有可能在安裝完 Tailwind 並嘗試編譯 CSS 時看到這個錯誤:

Error: PostCSS plugin tailwindcss requires PostCSS 8.

在大家都更新之前為了彌補 PostCSS 7 到 8 的差距，我們也在 npm 上發布了 PostCSS 7 的相容建置版本 @tailwindcss/postcss7-compat。

如果你遇到上述的錯誤，請移除 Tailwind 並改以相容建置版本重新安裝：

npm uninstall tailwindcss postcss autoprefixer
npm install -D tailwindcss@npm:@tailwindcss/postcss7-compat postcss@^7 autoprefixer@^9

相容建置版本與主要版本在每一處都是完全相同的，所以你不必擔心會失去任何特色功能。

若你的工具開始支援 PostCSS 8 了，你可以透過 -latest 標籤並重新安裝 Tailwind 和它的對等依賴套件 (peer-dependencies) 來關閉相容建置版本。

npm uninstall tailwindcss
npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

安裝