先决条件

HB 是一个功能丰富的框架,但同时也具有着一定的复杂性。本文将详细列出 HB 的环境要求,以便你可以正常地开发和使用 HB 模块和主题。

必要配置

hugo.toml

1[build]
2  writeStats = true

hugo.yaml

1build:
2  writeStats: true

hugo.json

1{
2   "build": {
3      "writeStats": true
4   }
5}
build.writeStats
用于收集站点所使用到的 classesidstags,以供 PurgeCSS 清除未使用的 CSS。

构建工具

推荐尽可能地使用以下构建工具的最新版本。

Go

HB 是一个模块化的框架,需要安装 Go 语言以下载和更新 Hugo 模块

1sudo pacman -S go

Hugo

Version

HB 使用 Hugo Pipes 来编译 SCSS,因此需要扩展版(extended)的 Hugo

若你位于中国大陆而没有 VPN 时,你需要先设置 target="_blank" rel=“noopener noreferrer”>Go 代理服务器

1go install -tags extended github.com/gohugoio/hugo@latest

Git

版本控制系统,可通过下载页面获得。

1sudo pacman -S git

Node.js

要求 Node.js 16 或后续版本。

HB 依赖以下 Node.js 包。

1sudo pacman -S nodejs
名称描述
PostCSS CLI用于转变样式。
RTLCSS将 LTR CSS 转换为 RTL,如果你没有 RTL 网站则可选。
Autoprefixer解析 CSS 并在 Can I Use 规则中添加对应的前缀。
PurgeCSS移除未使用的 CSS。

NPM 已被包含于 Node.js 安装中,你可以选择局部或全局地安装这些包。

局部安装
1npm i -D postcss-cli @fullhuman/postcss-purgecss autoprefixer rtlcss

局部安装将依赖写入 package.json,以便部署时通过 npm i 安装这些包,而无需记住这些繁杂的包名。

全局安装
1sudo npm i -g postcss-cli @fullhuman/postcss-purgecss autoprefixer rtlcss

该命令只需执行一次,后续的 HB 站点无需再次执行此命令。

两者都是有效的,HB 会优先局部查找需要的包。

注意

publishDir 必须public

它受到关于共享 PurgeCSS 配置的 HB 实现的限制。

该限制已于 v0.7.2 修复。

Hugo Server 生产模式的必要参数

若需要在生产模式下使用 Hugo Server,需要指定 --disableFastRender--renderToDisk,否则 PurgeCSS 和 PostCSS 会出现意想不到的问题。

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

请勿于语言范围配置中修改 hbhugopress 参数

HB 依赖于模块间配置的深度合并,然而语言范围的参数将会覆盖覆盖模块的配置,而非深度合并,这将导致各种意想不到的问题。比如以下的配置示例是不允许的。

hugo.toml

 1[language]
 2  [language.en]
 3    [language.en.params]
 4      [language.en.params.hb]
 5        foo = 'bar'
 6      [language.en.params.hugopress]
 7        foo = 'bar'
 8  [language.zh-hans]
 9    [language.zh-hans.params]
10      [language.zh-hans.params.hb]
11        foo = 'bar'
12      [language.zh-hans.params.hugopress]
13        foo = 'bar'

hugo.yaml

 1language:
 2  en:
 3    params:
 4      hb:
 5        foo: bar
 6      hugopress:
 7        foo: bar
 8  zh-hans:
 9    params:
10      hb:
11        foo: bar
12      hugopress:
13        foo: bar

hugo.json

 1{
 2   "language": {
 3      "en": {
 4         "params": {
 5            "hb": {
 6               "foo": "bar"
 7            },
 8            "hugopress": {
 9               "foo": "bar"
10            }
11         }
12      },
13      "zh-hans": {
14         "params": {
15            "hb": {
16               "foo": "bar"
17            },
18            "hugopress": {
19               "foo": "bar"
20            }
21         }
22      }
23   }
24}

请禁用 Cloudflare Rocket Loader

Cloudflare Rocket Loader 缺少了 DOMContentLoaded 事件,会导致很多模块失效,即便我们为此提供了一个补丁,但得不偿失,禁用该功能是目前最佳选择。

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