Zeabur｜如何解決 npm run css 執行過久無反應的問題？

更新日期： 2025 年 1 月 12 日

在使用 Tailwind CSS 進行專案開發時，執行 npm run css 指令卻長時間卡住或無反應？

這個問題通常與 --watch 參數 有關。

本文將針對此問題的成因與解決方案進行詳細說明，幫助新手理解並快速解決這個問題。

npm run css 是什麼？

在專案中執行 npm run css，通常會觸發 Tailwind CSS 的編譯指令，將你的 CSS 檔案從原始檔案轉換為最終可用於網頁的 CSS 檔案。

範例指令：

npx tailwindcss -i ./frontend/styles/app.css -o ./static/styles/app.css --watch

這段指令的作用是：

• npx tailwindcss：執行 Tailwind CSS 編譯器
• -i：指定輸入檔案（app.css）
• -o：指定輸出檔案（static/styles/app.css）
• --watch：啟用檔案監聽模式，持續監測檔案變動並自動重新編譯

為什麼 npm run css 會卡住？

原因：
npm run css 卡住的主要原因是使用了 --watch 模式。

--watch 問題說明

• --watch 會進入一個持續監聽狀態，只要 CSS 檔案有變動就會重新編譯。
• 這在 本地開發環境 非常有用，但在 伺服器環境（如 Zeabur 部屬）下，由於伺服器是一次性執行指令並自動終止，這種持續監聽會導致指令卡住且無法完成。

解決方案：移除 --watch 模式

要解決這個問題，只需要將 --watch 參數移除，讓 Tailwind CSS 單次編譯完成即可。

步驟 1：移除 --watch

將原本的 npm run css 指令從這樣：

npx tailwindcss -i ./frontend/styles/app.css -o ./static/styles/app.css --watch

改為：

npx tailwindcss -i ./frontend/styles/app.css -o ./static/styles/app.css

更新 package.json

打開 package.json，並修改 scripts 區塊：

{
  "scripts": {
    "css": "npx tailwindcss -i ./frontend/styles/app.css -o ./static/styles/app.css"
  }
}

這樣就會讓 npm run css 以單次執行的方式完成 CSS 編譯。

執行 npm run css

執行指令檢查是否已成功完成編譯：

npm run css

👉 這次指令應該會在短時間內完成，且輸出 ./static/styles/app.css 檔案。

其他最佳實踐建議

如何在本地使用 --watch？

如果你希望在 本地開發 時使用 --watch，但在伺服器上使用單次編譯，可以建立兩個不同的 npm 指令：

{
  "scripts": {
    "css": "npx tailwindcss -i ./frontend/styles/app.css -o ./static/styles/app.css",
    "css:watch": "npx tailwindcss -i ./frontend/styles/app.css -o ./static/styles/app.css --watch"
  }
}

• 本地使用： npm run css:watch
• 部屬使用： npm run css

如何自動編譯 CSS 並壓縮？

若需要壓縮 CSS，並移除未使用的樣式，可使用 purge 功能：

npx tailwindcss -i ./frontend/styles/app.css -o ./static/styles/app.css --minify

這樣會生成一個更小且優化過的 CSS 檔案，適用於正式上線。

如何檢查 Tailwind CSS 是否正確安裝？

如果執行 npm run css 出現以下錯誤：

Command 'npx tailwindcss' not found

請確認 Tailwind CSS 是否已安裝：

npm install -D tailwindcss

總結：解決步驟總覽

1. 確認 package.json 中的 npm run css 指令
2. 移除 --watch，改為單次編譯
3. 伺服器環境： 使用 npm run css 進行單次編譯
4. 本地開發： 可以保留 npm run css:watch 進行即時監控
5. 最佳實踐： 在正式上線前使用 --minify 進行壓縮

完成這些步驟後，你應該能夠成功解決 npm run css 執行過久的問題！