Publish
发布给定资源。
这一页解决什么问题
Resource 对象上的 Publish 方法把给定资源写入 publishDir。
有些文件必须出现在发布目录里,但页面不会链接它们:/.well-known/security.txt、robots.txt、各种 .well-known/ 校验文件、由数据动态生成的清单。这类「只需要落地、不需要 URL」的资源,用 Publish 最合适——它只发布,不返回任何值(returnType 就是 nil)。
什么时候用,什么时候别用
该用:
- 资源不需要在页面里被引用,但必须存在于
public/(.well-known/、校验文件); - 你已经拿到
RelPermalink,但更想让「我只是要发布它」这个意图写在模板里; - 在管道末端明确表达副作用。
别用:
- 需要 URL 去渲染
<img>/<a>→ 用RelPermalink或Permalink;它们也会发布资源,无需再调一次Publish; - 想「按需发布任意文件」(不是模板里造出来的资源)→ 把文件放进
static/目录更直接; - 要在管道里发布 → 用
resources.Publish函数(Publish是方法,管道里的写法不顺手)。
上游给出的对照很直观——需要发布但不关心返回值时,写:
go-html-template
{{ $resource.Publish }}而不是:
go-html-template
{{ $noop := $resource.Permalink }}完整示例(实测)
测量条件:Hugo 0.167.0 extended,Windows,最小站点,hugo.toml 里 [params] email = 'security@example.org'。下例用 resources.FromString 从字符串创建资源,然后发布它:
layouts/baseof.htmlgo-html-template
{{ $content := printf "Contact: mailto:%s\n" site.Params.email }}
{{ with resources.FromString ".well-known/security.txt" $content }}
{{ .Publish }}
{{ end }}构建后 public/.well-known/security.txt 真实存在,内容为:
Contact: mailto:security@example.org如果想让模板里也能看到路径,可以顺手输出 RelPermalink(这本身也会发布该资源):
go-html-template
{{ $content := printf "Contact: mailto:%s\n" site.Params.email }}
{{ with resources.FromString ".well-known/security.txt" $content }}
{{ .Publish }}
<p>已发布:{{ .RelPermalink }}</p>
{{ end }}实测渲染为:
html
<p>已发布:/.well-known/security.txt</p>你应当看到什么:{{ .Publish }} 在输出里什么都不打印(返回值是 nil/空),发布发生在渲染过程中;判断有没有生效,要去 public/ 目录里找文件,而不是看 HTML。
返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
resources.FromString 造出的资源 |
文件被写入 public/.well-known/security.txt,.Publish 返回空 |
否 |
| 图像处理后的资源 | 同样发布到 public/(实测 Resize "100x" 的结果被写入 public/images/) |
否 |
仅为取值而调用 Permalink/RelPermalink |
资源同样会被发布(副作用) | 否 |
{{ .Publish }} 直接输出 |
输出为空字符串,不显示任何内容 | 否 |
resources.Get 找不到文件(nil) |
—— | 是:nil pointer evaluating resource.Resource.Publish |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 页面里看不到任何变化,以为没生效 | Publish 不返回内容,只在渲染时写文件 |
去 public/ 里确认文件;或在同一 with 里输出 .RelPermalink |
| 没报错但结果不对 | 用 {{ .Publish }} 又套了 {{ with }},结果没进分支 |
返回值是空值,with 判为假 |
直接写 {{ .Publish }},不要用它的返回值做条件 |
| 没报错但结果不对 | 同一资源被发布到意料之外的路径 | resources.FromString 的第一个参数就是发布路径 |
用想落地的相对路径(如 .well-known/security.txt) |
| 报错看不懂 | nil pointer evaluating resource.Resource.Publish |
resources.Get 没找到文件 |
用 {{ with resources.Get "…" }} 包住 |
更多排查入口见故障排查。