问题排查

已知问题清单和相应的解决方案。

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 是一个不错的选择。