fmt.Warnf
从模板记录一条 WARNING 日志。
这一页解决什么问题
模板里发现问题,但又不想让整个站点构建失败:某个可选参数没配、某个字段已弃用、某个资源找不到但还能降级渲染。warnf 把这些信息写进构建日志(WARNING 级别),构建照常完成——这样读者看不到问题,作者能在终端里看到。
什么时候用,什么时候别用
该用:
- 可降级的问题(有默认值、有回退路径);
- 主题/短代码提醒使用者「你少配了一个可选项」。
别用:
- 问题无法继续 → 用
fmt.Errorf,让构建失败; - 希望使用者能按 ID 关掉这条警告 → 用
fmt.Warnidf; - 调试时想把值打到产物里 → 用
fmt.Print。
用法
Go 的 fmt 包的文档描述了格式字符串的结构与内容。
warnf 函数对格式字符串求值,然后把结果输出到 WARNING 日志。Hugo 对每条唯一消息只输出一次,以免日志被重复警告淹没。
go-html-template
{{ warnf "The %q shortcode was unable to find %s. See %s" .Name $file .Position }}用 warnidf 函数可以按需抑制特定的警告。
用 warnf 调试时,如果不想让重复消息被抑制,可以用 math.Counter 函数让每条消息唯一。例如:
go-html-template
{{ range site.RegularPages }}
{{ .Section | warnf "%#[2]v [%[1]d]" math.Counter }}
{{ end }}完整示例(实测)
layouts/_partials/optional-flag.htmlgo-html-template
{{ warnf "test warning %s" "x" }}okHugo 0.167.0 实测:构建成功(退出码 0),控制台出现一行
WARN test warning x页面产物是 ok(warnf 的返回值不会占位输出)。
你应当看到什么:WARN 后面有两个空格,然后是格式化后的消息。注意「只输出一次」的行为——下面这段模板重复调用三次:
go-html-template
{{ range seq 3 }}{{ warnf "same message" }}{{ end }}ok实测只输出一行 WARN same message,而不是三行。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'zh-CN'),Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
| 调用一次(实测) | 日志出现 WARN test warning x |
否(退出码 0) |
同一消息调用 3 次(实测 range seq 3) |
日志只有一行同类警告 | 否 |
| 消息里的格式动词写错 | 输出 %!... 形式的文本(与 fmt.Printf 同源) |
否 |
| 返回类型 | string;直接放在模板里不会输出可见内容 |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 循环里只看到一条警告,以为循环没跑 | Hugo 对相同消息只输出一次(实测 3 次只出 1 行) | 用 math.Counter 让每条消息唯一(上游示例即如此) |
| 没报错但结果不对 | 页面上出现 %!s(...) |
格式动词与参数类型不符 | 检查占位符与参数 |
| 报错看不懂 | 构建被中止 | 用了 fmt.Errorf 而不是 warnf |
只要警告就用本函数 |
更多排查入口见故障排查。