GetPage
根据给定路径返回 Page 对象。
这一页解决什么问题
模板里常常要「按路径拿到另一个页面」:跨栏目引用、取固定页面做首页区块、从当前页找同目录的兄弟页。GetPage 就是这条路:给一个路径,返回 Page 对象;找不到时返回 nil,因此必须做防御。
什么时候用,什么时候别用
该用:
- 取已知路径的页面(
/about/、/docs/guide/beta/); - 从当前页按相对路径取同目录 / 上级的页面。
别用:
- 想按标题或参数找页面 → 用
where从集合里筛; - 想拿当前页 → 直接用
.; - 想在
range里遍历一堆页面 → 用.Pages/.RegularPages,不要循环调用GetPage; - 拿到结果不判断就访问字段 → 路径写错时会直接报错。
用法
GetPage 方法在 Site 对象上也可用。详见说明。
在 Page 对象上使用 GetPage 方法时,请指定相对于当前目录或相对于 content 目录的路径。
如果 Hugo 无法把路径解析为页面,该方法返回 nil。如果路径有歧义,Hugo 会抛出错误并中止构建。
内容结构如下:
tree
content/
├── works/
│ ├── paintings/
│ │ ├── _index.md
│ │ ├── starry-night.md
│ │ └── the-mona-lisa.md
│ ├── sculptures/
│ │ ├── _index.md
│ │ ├── david.md
│ │ └── the-thinker.md
│ └── _index.md
└── _index.md下面的示例展示了渲染 works/paintings/the-mona-lisa.md 的结果:
layouts/works/page.htmlgo-html-template
{{ with .GetPage "starry-night" }}
{{ .Title }} → Starry Night
{{ end }}
{{ with .GetPage "./starry-night" }}
{{ .Title }} → Starry Night
{{ end }}
{{ with .GetPage "../paintings/starry-night" }}
{{ .Title }} → Starry Night
{{ end }}
{{ with .GetPage "/works/paintings/starry-night" }}
{{ .Title }} → Starry Night
{{ end }}
{{ with .GetPage "../sculptures/david" }}
{{ .Title }} → David
{{ end }}
{{ with .GetPage "/works/sculptures/david" }}
{{ .Title }} → David
{{ end }}完整示例:取同目录的另一个页面
最小站点:content/docs/guide/alpha.md 与 content/docs/guide/beta.md。模板放在 layouts/_default/single.html:
layouts/_default/single.htmlgo-html-template
{{ with .GetPage "beta" }}
<a href="{{ .RelPermalink }}">{{ .Title }}</a>
{{ else }}
<p>没有找到该页面</p>
{{ end }}hugo --source <站点目录> --ignoreCache 构建后,alpha 页面输出:
html
<a href="/docs/guide/beta/">Beta</a>你应当看到什么:相对路径 beta 与相对 content 根的 /docs/guide/beta 得到同一个页面(实测两者都渲染出 Beta);写成不存在的路径(如 nope)时 with 判为假,输出兜底文案而不是让构建失败。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,Windows;调用位置是 /docs/guide/alpha 页面。
| 调用 | 结果 | 是否报错 |
|---|---|---|
.GetPage "beta"(相对当前目录) |
同目录页面 | 否 |
.GetPage "/docs/guide/beta"(相对 content 根) |
同一个页面 | 否 |
.GetPage "guide"(相对父目录) |
/docs/guide 这个 section 页 |
否 |
.GetPage "nope" |
nil,with 判为假 |
否 |
对 nil 结果接着访问 .Title |
—— | 是:模板渲染报错 |
| 路径有歧义 | —— | 是:Hugo 报错并中止构建(上游已说明) |
| 返回类型 | page.Page(可能为 nil) |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 构建报错 | nil pointer evaluating …Title |
路径写错,GetPage 返回 nil |
用 {{ with .GetPage "…" }} 包起来,并加 else 给出提示或 errorf |
| 没报错但结果不对 | 相对路径取到的不是预期页面 | 相对路径以当前页面所在目录为基准 | 不确定时写以 / 开头、相对 content 根的路径 |
| 构建报错 | 路径歧义导致构建中止 | 同一路径匹配到多个页面 | 写完整路径,或改用 .Site.GetPage |
更多排查入口见故障排查。