Permalink
返回给定页面的永久链接。
这一页解决什么问题
.Permalink 返回页面的绝对 URL:baseURL + 语言前缀(如有)+ 路径 + 尾斜杠。适合放进 RSS、站点地图、<link rel="canonical">、分享链接、Open Graph 的 og:url 这类离开本站的场合。
它与 .RelPermalink 的区别只有一处:绝对还是相对。本站内部的 <a href> 应该用 .RelPermalink,这样换域名、换子路径部署时都不用改模板。
什么时候用,什么时候别用
该用:
- RSS / sitemap / canonical /
og:url等需要完整 URL 的输出; - 需要把当前站点地址发给外部系统(Webhook、JSON 输出)。
别用:
- 站内
<a href>/<img src>→ 用.RelPermalink(本地hugo server预览、子路径部署都不会错); - 需要资源文件的 URL → 用资源的
.Permalink(Resources对象上也有同名方法); - 不想被
baseURL影响 → 那就是.RelPermalink。
选哪个:
| 场景 | 用哪个 |
|---|---|
| 页面里的站内链接 | .RelPermalink |
| RSS / sitemap / canonical | .Permalink |
| 页面包内图片的 src | 图片资源对象的 .RelPermalink |
| 同一份模板想在任意域名下工作 | .RelPermalink |
用法
项目配置:
toml
title = 'Documentation'
baseURL = 'https://example.org/docs/'模板:
go-html-template
{{ $page := .Site.GetPage "/about" }}
{{ $page.Permalink }} → https://example.org/docs/about/完整示例:三种 baseURL 下的同一页
模板(layouts/_default/single.html):
layouts/_default/single.htmlgo-html-template
<link rel="canonical" href="{{ .Permalink }}">
<a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a>实测(Hugo 0.167.0,同一份内容,仅改 baseURL),页面 /posts/post-2/:
baseURL |
.Permalink |
.RelPermalink |
|---|---|---|
https://example.org/ |
https://example.org/posts/post-2/ |
/posts/post-2/ |
https://example.org/docs/ |
https://example.org/docs/posts/post-2/ |
/docs/posts/post-2/ |
https://example.org/docs/(中文页 /zh/posts/post-1/) |
https://example.org/docs/zh/posts/post-1/ |
/docs/zh/posts/post-1/ |
你应当看到什么:baseURL 尾部的 /docs/ 会出现在两者里——.RelPermalink 是「相对域名」,不是「相对站点根」。所以把站点部署到子目录时,.RelPermalink 依然可以直接用,不需要手工拼 /docs。
返回值边界(实测)
| 情况 | .Permalink |
是否报错 |
|---|---|---|
| 普通页面 | baseURL + 路径,以 / 结尾(实测) |
否 |
baseURL 带子路径 |
子路径被保留(实测 https://example.org/docs/posts/post-2/) |
否 |
| 非默认语言页面 | 含语言段(实测 …/zh/posts/post-1/) |
否 |
前置元数据设了 slug |
URL 使用 slug(实测 /posts/first-post/) |
否 |
关闭美化 URL(uglyURLs = true) |
以 .html 结尾——上游说明的行为,本站测试站未启用该配置,故不列实测输出 |
否 |
通过 --baseURL 命令行覆盖 |
立即生效(实测同一次构建内所有页面都改用新值) | 否 |
| 返回类型 | string(绝对 URL) |
否 |
更多排查入口见故障排查。