math.Counter
返回一个全局计数器值,函数每被调用一次就递增一次。
这一页解决什么问题
需要一个「每次调用都不一样」的值:让重复的警告各占一行不被去重、给 resources.FromString 的目标路径(同时也是缓存键)加上唯一后缀。math.Counter 提供全局自增计数,每次构建从 1 开始。
layouts/page.htmlgo-html-template
{{ warnf "page.html called %d times" math.Counter }}WARN page.html called 1 times
WARN page.html called 2 times
WARN page.html called 3 times什么时候用,什么时候别用
该用:
- 生成唯一的警告/日志(
warnf会抑制完全相同的消息,加计数器就能都打出来); - 为
resources.FromString生成唯一目标路径,避免同路径缓存互相覆盖。
别用:
- 想给页面分配固定编号(目录序号、静态 id)→ 计数器受并发影响,每次构建的值都可能不同(上游明确说明),请改用
.Weight、ordinal或自己维护的数据; - 想在循环里生成序号 → 直接用
range的索引或seq,语义更清晰; - 想要随机数 → 用
math.Rand。
该计数器对单语言与多语言项目都是全局的,每次构建的初始值为 1。
完整示例:连续三次调用
layouts/_partials/counter-demo.htmlgo-html-template
<p>{{ math.Counter }}-{{ math.Counter }}-{{ math.Counter }}(类型 {{ printf "%T" math.Counter }})</p>Hugo 0.167.0 实测渲染为:
html
<p>1-2-3(类型 uint64)</p>你应当看到什么:三次调用依次得到 1、2、3;返回类型是 uint64。再次强调:如果这个片段被多个页面同时渲染,Hugo 并行执行会让「哪个页面拿到哪个数字」不稳定——不要把它当作页面编号使用。
可以用这个函数来:
- 生成如上例所示的唯一警告信息;
warnf函数会抑制重复的消息 - 为
resources.FromString函数生成唯一的目标路径,此时目标路径同时也是缓存键
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点,Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
| 同一模板里连续调用三次 | 1、2、3 |
否 |
| 每次构建 | 计数从 1 重新开始(上游说明:初始值为 1) | 否 |
| 多页面并行构建 | 值在多页之间交错,不保证稳定(上游说明) | 否 |
| 传入参数 | 该函数无参数;传参会导致参数个数错误 | 是 |
| 返回类型 | uint64 |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 页面编号每次构建都不一样 | 计数器受并发影响(上游明确说明) | 换用稳定来源:.Weight、ordinal、数据文件里的序号 |
| 没报错但结果不对 | 想看到 3 条警告,实际只出现 1 条 | warnf 会去重相同消息 |
把 math.Counter 放进消息里 |
| 没报错但结果不对 | 生成的资源互相覆盖 | 目标路径相同、缓存键也相同 | 用 math.Counter 参与目标路径,或改用内容哈希 |
更多排查入口见故障排查。