問題排查

已知問題清單和相應的解決方案。

POSTCSS CLI

1Error: Error building site: POSTCSS: failed to transform "hb/scss/index.css" (text/css). Check your PostCSS installation.

The error above will appear if there isn’t POSTCSS CLI installed on your environment.

1npm i postcss-cli

Or

1sudo npm i -g postcss-cli

RTLCSS

1POSTCSS: failed to transform "hb/scss/index.rtl.css" (text/css): Plugin Error: Cannot find package 'rtlcss' imported from /usr/lib/node_modules/postcss-cli/index.js'

The error above will be reached if there isn’t RTLCSS installed on your machine.

1npm i rtlcss

Or

1sudo npm i -g rtlcss

PurgeCSS Configuration

1Error: Error building site: POSTCSS: failed to transform "hb/scss/index.css" (text/css): Error: Failed to parse runtime PurgeCSS config: Error: ENOENT: no such file or directory, open './public/.build/purgecss.json'.
2Please enable the "--renderToDisk" if you are using Hugo server.

It happens on the case of using Hugo server on production mode without the --renderToDisk and --disableFastRender flags.

1hugo server \
2  -e production \
3  --renderToDisk \
4  --disableFastRender \
5  -p 1313 \
6  -b http://localhost:1313

Hugo Stats File

1Error: Error building site: POSTCSS: failed to transform "hb/scss/index.css" (text/css): /home/hbstack/Projects/hbstack/hb/purgecss.config.js:5
2        throw new Error('Hugo stats file not found, please enable the "build.writeStats".')
3        ^
4Error: Hugo stats file not found, please enable the "build.writeStats".

hugo.toml

1[build]
2  writeStats = true

hugo.yaml

1build:
2  writeStats: true

hugo.json

1{
2   "build": {
3      "writeStats": true
4   }
5}

Autoprefixer

1Error: Error building site: POSTCSS: failed to transform "hb/scss/index.css" (text/css): Error: Cannot find module '/usr/lib/node_modules/autoprefixer'
1npm i postcss-cli

Or

1sudo npm i -g postcss-cli

POSTCSS PurgeCSS

1Error: Error building site: POSTCSS: failed to transform "hb/scss/index.css" (text/css): Error: Cannot find module '@fullhuman/postcss-purgecss'
1npm i @fullhuman/postcss-purgecss

Or

1sudo npm i -g @fullhuman/postcss-purgecss

效率極低的構建性能

導致網站構建速度減慢的因素有很多,下面列出了一些常見的因素。

  1. 低效的磁盤 IO 性能,如外部磁盤。
  2. Windows Defender 或其他殺毒軟件的實時保護。
  3. 同步軟件(如 OneDrive、NutStore)正在監視發佈文件夾。

我們建議在固態硬盤等高性能磁盤上構建網站。如果可能,還建議在 Linux 系統上構建,因為它通常比 Windows 等其他操作系統更快。

對於 Windows 用戶來說,WSL2 是一個不錯的選擇。

razonyang
2024年7月23日 星期二 2022年12月19日 星期一