BaseURL
返回项目配置中定义的 base URL。
这一页解决什么问题
BaseURL 把配置里 baseURL 的值原样交回模板,回答的是「本站发布在哪个地址」。它不负责把某个路径变成可用链接——这两件事在 base URL 带子路径(如 https://example.org/docs/)时会分道扬镳。
本站的 baseURL 就是带子路径的写法,所以这个区别值得记住:.Site.BaseURL 只是回显配置,拼链接是 absURL / relURL 的职责。
什么时候用,什么时候别用
该用:
- 只是要显示配置中的根地址,例如页脚一行「本站地址:…」;
- 排查构建:确认本次构建实际用的 base URL(命令行
--baseURL会覆盖配置文件的值)。
别用:
- 要把路径变成绝对 URL → 用
absURL或absLangURL;相对链接 → 用relURL或relLangURL。实测 base URL 为https://example.org/docs/时,absURL "images/logo.png"→https://example.org/docs/images/logo.png,而手写.Site.BaseURL加路径只在配置恰好带结尾斜杠时才碰巧正确; - 要链接某个页面 → 用该页面的
.Permalink/.RelPermalink(见 methods/page),它们会自动带上子路径与语言前缀; - 想「规范化」base URL 的写法 → 别指望配置原样保留:实测配置写成不带结尾斜杠的
https://example.org,.Site.BaseURL会返回https://example.org/。
用法
项目配置:
toml
baseURL = 'https://example.org/docs/'模板:
go-html-template
{{ .Site.BaseURL }} → https://example.org/docs/完整示例(实测)
在最小站点里设 baseURL = 'https://example.org/docs/',把下面三行放进任意会渲染 HTML 的模板(如 home 模板 layouts/index.html):
layouts/index.htmlgo-html-template
{{ .Site.BaseURL }} → https://example.org/docs/
{{ absURL "images/logo.png" }} → https://example.org/docs/images/logo.png
{{ relURL "images/logo.png" }} → /docs/images/logo.png你应当看到什么:三个结果都带上了 /docs/ 前缀。把 base URL 改成不带结尾斜杠的 https://example.org,第一行变成 https://example.org/(Hugo 自动补斜杠),后两行则变成 https://example.org/images/logo.png 与 /images/logo.png——这正说明拼链接要交给 URL 函数,不能手接字符串。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点,Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
baseURL = 'https://example.org/docs/' |
https://example.org/docs/(保留子路径与结尾斜杠) |
否 |
baseURL = 'https://example.org'(无结尾斜杠) |
https://example.org/(Hugo 补上斜杠) |
否 |
命令行传 --baseURL |
覆盖配置文件中的值 | 否 |
配置里完全没有 baseURL |
使用 Hugo 默认值 https://example.org/ |
否 |
| 返回值类型 | string |
否 |
最后一行是排查时的陷阱:默认值恰好是一个看起来正常的地址,所以「页面上链接全指向 example.org」几乎总是因为配置文件没被读到。