urls.AbsURL
返回绝对 URL。
这一页解决什么问题
有些地方必须给出带域名与协议的完整地址:RSS/Atom 里的 <link>、Open Graph 的 og:url、结构化数据、sitemap、邮件模板。写死域名会在换域名或切到子路径部署时失效,urls.AbsURL 让地址跟着项目配置里的 baseURL 走。它的全部难点只有一句话——结果取决于输入是否以斜杠开头。
什么时候用,什么时候别用
该用:
- 需要完整地址的场合(RSS、OG、结构化数据、sitemap、邮件);
- 希望地址随
baseURL自动变化。
别用:
- 多语言站点 → 用
urls.AbsLangURL:它会带上语言前缀,absURL不会; - 站内相对地址(
<a href>、样式、脚本、图片)→ 用urls.RelURL; - 页面之间的链接 → 用
urls.Ref或urls.RelRef,它们会校验目标页面是否存在; - 只是拼接片段 → 用
urls.JoinPath。
用法
使用多语言配置时,请改用 urls.AbsLangURL 函数。返回的 URL 取决于:
- 输入是否以斜杠(
/)开头 - 项目配置中的
baseURL
输入不以斜杠开头
如果输入不以斜杠开头,结果 URL 中的路径相对于项目配置里的 baseURL。
baseURL = https://example.org/ 时
{{ absURL "" }} → https://example.org/
{{ absURL "articles" }} → https://example.org/articles
{{ absURL "style.css" }} → https://example.org/style.cssbaseURL = https://example.org/docs/ 时
{{ absURL "" }} → https://example.org/docs/
{{ absURL "articles" }} → https://example.org/docs/articles
{{ absURL "style.css" }} → https://example.org/docs/style.css输入以斜杠开头
如果输入以斜杠开头,结果 URL 中的路径相对于项目配置里 baseURL 的协议加主机部分。
baseURL = https://example.org/ 时
{{ absURL "/" }} → https://example.org/
{{ absURL "/articles" }} → https://example.org/articles
{{ absURL "/style.css" }} → https://example.org/style.cssbaseURL = https://example.org/docs/ 时
{{ absURL "/" }} → https://example.org/
{{ absURL "/articles" }} → https://example.org/articles
{{ absURL "/style.css" }} → https://example.org/style.css完整示例(实测)
[{{ absURL "" }}]|[{{ absURL "articles" }}]|[{{ absURL "/articles" }}]Hugo 0.167.0 实测输出,baseURL = "https://example.org/" 时:
[https://example.org/]|[https://example.org/articles]|[https://example.org/articles]把 baseURL 换成 "https://example.org/docs/" 后,同一段模板实测输出:
[https://example.org/docs/]|[https://example.org/docs/articles]|[https://example.org/articles]你应当看到什么:前两项带上了 /docs/ 前缀,第三项没有——输入带了前导斜杠,absURL 只把它接到「协议 + 主机」后面,站点子路径被丢掉了。在子路径部署的站点上,这正是「本地看着对、线上 404」的常见原因。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点,Windows;baseURL 分别取 https://example.org/ 与 https://example.org/docs/。
| 输入 | 结果 | 是否报错 |
|---|---|---|
"" |
等于 baseURL(含结尾斜杠) |
否 |
"articles" |
baseURL 的路径部分 + articles |
否 |
"/articles" |
协议 + 主机 + /articles,丢掉 baseURL 的路径(实测 /docs/ 部署下得到 https://example.org/articles) |
否 |
"/" |
协议 + 主机 + / |
否 |
| 返回类型 | string,永远不是 nil |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 站点部署到子路径后,RSS/OG 里的地址 404 | 输入带前导斜杠,丢掉了子路径 | 省略前导斜杠(实测去掉后才带上 /docs/) |
| 没报错但结果不对 | 切换语言后地址指向默认语言 | 多语言站点用了 absURL,没有语言前缀 |
改用 urls.AbsLangURL |
| 没报错但结果不对 | 本地预览的域名跑到了线上 | baseURL 是本地地址或被 --baseURL 临时覆盖 |
构建时用生产环境的 baseURL |
更多排查入口见故障排查。