日志
用 --logLevel 控制构建日志的详细程度,把输出重定向到文件,用 warnf / errorf 从模板里打印提示,以及打开 LiveReload 调试日志。
开始之前,你需要
- 能在项目根目录执行
hugo/hugo build - 遇到的是「构建有问题但看不清发生了什么」,或想给模板加上自己的校验提示
读完之后你能
- 按需要选择 error / warn / info / debug 四个级别,并知道默认为什么看不到 INFO
- 把构建输出重定向到文件,并避开 Windows 上的编码坑
- 用
warnf/warnidf/errorf/erroridf在模板里报告问题,并知道哪种可以被ignoreLogs屏蔽
日志是排查里成本最低的一手证据:不用改模板、不用猜,只要把级别调高,Hugo 就会把自己做了什么、在哪一步停了说清楚。这一页解决三件事——看多少(级别)、看到哪去(重定向)、怎么让模板也说话(模板函数)。
命令行
用 --logLevel 命令行标志启用控制台日志。Hugo 有四个日志级别,级别越高,显示的消息越详细:
error- 只显示错误消息。
bash
hugo build --logLevel error warn- 显示警告与错误消息。
bash
hugo build --logLevel warn info- 显示信息、警告与错误消息。
bash
hugo build --logLevel info debug- 显示调试、信息、警告与错误消息。
bash
hugo build --logLevel debug
为什么默认看不到 INFO:默认级别相当于 warn,只保证警告与错误一定出现。弃用提示、构建步骤耗时这类信息属于 INFO,不主动指定就看不到。要观察细节时,从 info 或 debug 开始逐级放宽。
你应当看到什么:实测在 Hugo v0.167.0 上,--logLevel info 的输出形如(每行以级别标签开头,标签后跟两个空格):
INFO static: syncing static files to \ duration 4.3307ms
INFO build: step process substep collect files 949 files_total 949 pagesources_total 948 resourcesources_total 1 duration 18.1492ms
INFO build: step assemble duration 191.2217ms判据:出现 INFO 开头的行,说明级别已生效;--logLevel debug 还会额外出现 DEBUG 行。若输出与不指定级别时完全一样,先确认标志写在子命令之后、且拼写正确(用 hugo build --help 核对)。
弃用提示也属于 INFO 级别,升级后想看到它们就必须显式指定 --logLevel info,详见弃用说明。
把输出写入文件
构建输出较长时,可以重定向到文件后再慢慢查看。下面的写法把标准输出与标准错误一并写入 build.log:
hugo build --logLevel info > build.log 2>&1Windows PowerShell 里同样可以:
hugo build --logLevel info *> build.log重定向只影响输出去向,不改变日志级别;要调整显示的内容,仍然通过 --logLevel 控制。
编码提示:Windows PowerShell 5.1 的
>/>>默认写出 UTF-16LE(带 BOM),在部分编辑器里会显示成乱码。用 PowerShell 7,或改用hugo build --logLevel info 2>&1 | Out-File -Encoding utf8 build.log。注意不要把这种重定向用在内容文件或配置文件上——Hugo 读到带 BOM 的 TOML 会直接报toml: invalid character at start of key: U+00FF。
模板函数
也可以用模板函数把警告或错误打印到控制台。这类函数通常用于报告数据校验错误、文件缺失等情况。它们位于 fmt 函数组中:
| 函数 | 签名 | 行为 |
|---|---|---|
warnf |
fmt.Warnf FORMAT [INPUT] |
记录一条 WARNING;相同消息只打印一次 |
warnidf |
fmt.Warnidf ID FORMAT [INPUT] |
记录一条带 ID 的 WARNING,可被 ignoreLogs 屏蔽 |
errorf |
fmt.Errorf FORMAT [INPUT] |
记录一条 ERROR,并使构建失败 |
erroridf |
fmt.Erroridf ID FORMAT [INPUT] |
记录一条带 ID 的 ERROR,并使构建失败,可被 ignoreLogs 屏蔽 |
warnidf 与 erroridf 记录的日志带有消息 ID,把该 ID 加入项目配置的 ignoreLogs 数组即可屏蔽对应的提示,warnf 与 errorf 则不能这样屏蔽。
你应当看到什么:warnidf 会在控制台打印提示,并顺带告诉你怎么屏蔽它:
WARN You should consider fixing this.
You can suppress this warning by adding the following to your project configuration:
ignoreLogs = ['warning-42']按提示把 ID 加进配置即可:
ignoreLogs = ["warning-42"]什么时候用:数据校验(例如某个前置元数据字段必须存在)、引用了不存在的文件、短代码参数缺失。什么时候别用:把 errorf 当成断言随手加在循环里——它会让构建失败,一旦触发,站点就发布不出去;想让构建继续、只留提示,用 warnf。
LiveReload
要在浏览器中记录 Hugo 的 LiveReload 请求,在运行开发服务器时给 URL 加上这个查询字符串:
debug=LR-verbose例如:
http://localhost:1313/?debug=LR-verbose然后在浏览器的开发者工具控制台中观察重载请求,并确认已启用开发者工具的「保留日志」(preserve log)选项,否则页面刷新时日志会被清空。
你应当看到什么:每次保存文件后,控制台里出现一条 LiveReload 相关的请求记录。看不到时先检查「保留日志」是否勾选,再确认地址栏里确实带了 ?debug=LR-verbose。
常见坑
命令找不到
grep: command not found(Windows):用Select-String,例如hugo build --logLevel info | Select-String deprecate;hugo: command not found:见故障排查的「症状 A:命令找不到」;hugo build在旧版本上不被识别:旧版可能只支持不带子命令的hugo,用hugo --help确认。
没有报错但结果不对
- 调高级别却没变化:标志位置写错(要跟在
hugo build之后),或站点本身确实没有该级别的日志; - 重定向后文件是空的:日志可能全部走了标准错误。用
> build.log 2>&1(Bash)或*> build.log(PowerShell)把两路都收进去; warnf只打印了一次:这是去重行为,不是循环没执行。调试循环时加math.Counter制造唯一消息,做法见检查与调试;ignoreLogs写了却不生效:只有带 ID 的warnidf/erroridf能被屏蔽,warnf/errorf不行;另外 ID 必须与代码里写的完全一致。
报错看不懂