urls.AbsLangURL
返回带语言前缀(如果有)的绝对 URL。
这一页解决什么问题
多语言站点里需要完整地址的场合(RSS、Open Graph、结构化数据、邮件),地址还必须带上当前语言的语言前缀。用 urls.AbsURL 会漏掉前缀,读者点开就会被带到默认语言版本;urls.AbsLangURL 会按当前渲染的语言补上前缀。
什么时候用,什么时候别用
该用:
- 多语言站点的 RSS、OG、结构化数据、邮件模板;
- 单语言站点也可以放心使用(没有语言前缀时结果与
urls.AbsURL同类,但统一写法更省心)。
别用:
- 站内相对地址 → 用
urls.RelLangURL; - 明确不需要语言前缀(例如全站共用的静态资源)→ 用
urls.AbsURL或urls.RelURL; - 页面之间的链接 → 用
urls.Ref(它还能指定lang与outputFormat)。
用法
单语言与多语言配置都可以使用该函数。返回的 URL 取决于:
- 输入是否以斜杠(
/)开头 - 项目配置中的
baseURL - 语言前缀(如果有)
下文示例使用这份项目配置:
defaultContentLanguage = 'en'
defaultContentLanguageInSubdir = true
[languages.en]
weight = 1
[languages.es]
weight = 2输入不以斜杠开头
如果输入不以斜杠开头,结果 URL 中的路径相对于项目配置里的 baseURL。
以 baseURL = https://example.org/ 渲染 en 站点时
{{ absLangURL "" }} → https://example.org/en/
{{ absLangURL "articles" }} → https://example.org/en/articles
{{ absLangURL "style.css" }} → https://example.org/en/style.css以 baseURL = https://example.org/docs/ 渲染 en 站点时
{{ absLangURL "" }} → https://example.org/docs/en/
{{ absLangURL "articles" }} → https://example.org/docs/en/articles
{{ absLangURL "style.css" }} → https://example.org/docs/en/style.css输入以斜杠开头
如果输入以斜杠开头,结果 URL 中的路径相对于项目配置里 baseURL 的协议加主机部分。
以 baseURL = https://example.org/ 渲染 en 站点时
{{ absLangURL "/" }} → https://example.org/en/
{{ absLangURL "/articles" }} → https://example.org/en/articles
{{ absLangURL "/style.css" }} → https://example.org/en/style.css以 baseURL = https://example.org/docs/ 渲染 en 站点时
{{ absLangURL "/" }} → https://example.org/en/
{{ absLangURL "/articles" }} → https://example.org/en/articles
{{ absLangURL "/style.css" }} → https://example.org/en/style.css完整示例(实测)
[{{ absLangURL "" }}]|[{{ absLangURL "articles" }}]|[{{ absLangURL "/articles" }}]Hugo 0.167.0 实测输出(项目配置同上,渲染 en 站点),baseURL = "https://example.org/" 时:
[https://example.org/en/]|[https://example.org/en/articles]|[https://example.org/en/articles]baseURL = "https://example.org/docs/" 时:
[https://example.org/docs/en/]|[https://example.org/docs/en/articles]|[https://example.org/en/articles]你应当看到什么:语言前缀 /en/ 始终存在;但与 urls.AbsURL 一样,带前导斜杠的第三项丢掉了 /docs/,退回到「协议 + 主机 + 语言前缀」。子路径部署时这一项会 404。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,Windows;多语言配置 defaultContentLanguage='en'、defaultContentLanguageInSubdir=true,语言 en、es;渲染 en 站点。
| 输入 | 结果 | 是否报错 |
|---|---|---|
"" |
baseURL + 语言前缀(实测为 https://example.org/en/) |
否 |
"articles" |
https://example.org/en/articles |
否 |
"/articles" |
https://example.org/en/articles;baseURL 为 /docs/ 时是 https://example.org/en/articles,丢掉 /docs/ |
否 |
"/" |
https://example.org/en/ |
否 |
| 返回类型 | string,永远不是 nil |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | RSS 里的链接指向默认语言 | 用了 urls.AbsURL,它不加语言前缀 |
改用本函数 |
| 没报错但结果不对 | 子路径部署后前导斜杠那项 404 | 输入带前导斜杠,丢掉了站点子路径(实测) | 省略前导斜杠 |
| 没报错但结果不对 | 语言前缀没出现 | defaultContentLanguageInSubdir 为 false,默认语言本来就不带前缀 |
按需在配置里打开该选项,或接受默认语言无前缀的结果 |
更多排查入口见故障排查。