Path
返回给定页面的逻辑路径。
这一页解决什么问题
一个页面有两个「身份」:发布出去的 URL(会被 slug、url、语言前缀、baseURL 子路径改写)和在 Hugo 逻辑树中的位置(稳定、与 URL 无关)。.Path 返回后者:
{{ .Path }} → /posts/post-1它在两种场景里不可替代:一是当作查找页面的键(site.GetPage、Page.GetPage、Page.Ref、ref/relref 短代码都用逻辑路径),二是当稳定的唯一标识(例如生成锚点、给列表项加 id、排查「两个页面 URL 不同但其实是同一逻辑位置」)。
什么时候用,什么时候别用
该用:
- 给
site.GetPage/Page.GetPage/Page.Ref/Page.RelRef传参数; - 需要「忽略 URL 修饰符」的稳定标识;
- 多语言站点里判断两个页面是不是同一个逻辑位置(不同语言的同名页面
.Path相同)。
别用:
- 要链接 → 用
.RelPermalink或.Permalink; - 要磁盘上的源文件路径 → 用
.File(页面包与页面包之外的资源要用不同方法); - 想拿 URL 里的 slug → 用
.Slug。
用法
Page 对象上的 Path 方法返回给定页面的逻辑路径,无论该页面是否由文件支撑。
{{ .Path }} → /posts/post-1Page 对象上的 Path 方法返回的值与内容格式、语言,以及 slug、url 等前置元数据 URL 修饰符无关。
查找页面
以下方法、函数和短代码使用逻辑路径来查找给定页面:
| 方法 | 函数 | 短代码 |
|---|---|---|
Site.GetPage |
urls.Ref |
ref |
Page.GetPage |
urls.RelRef |
relref |
Page.Ref |
||
Page.RelRef |
||
Shortcode.Ref |
||
Shortcode.RelRef |
逻辑树
正如文件路径构成文件树,逻辑路径构成逻辑树。
文件树:
content/
└── s1/
├── p1/
│ └── index.md
└── p2.md同样的内容用逻辑树表示:
content/
└── s1/
├── p1
└── p2这两棵树的一个关键区别是 p1 到 p2 的相对路径:
- 在文件树中,p1 到 p2 的相对路径是
../p2.md - 在逻辑树中,相对路径是
p2
示例
以下示例演示 Path 方法在不同情形下的行为。
单语言项目
请注意,逻辑路径与内容格式和 URL 修饰符无关。
| 文件路径 | 前置元数据 slug | 逻辑路径 |
|---|---|---|
content/_index.md |
/ |
|
content/posts/_index.md |
/posts |
|
content/posts/post-1.md |
foo |
/posts/post-1 |
content/posts/post-2.html |
bar |
/posts/post-2 |
多语言站点
请注意,逻辑路径与内容格式、语言标识符和 URL 修饰符无关。
| 文件路径 | 前置元数据 slug | 逻辑路径 |
|---|---|---|
content/_index.en.md |
/ |
|
content/_index.de.md |
/ |
|
content/posts/_index.en.md |
/posts |
|
content/posts/_index.de.md |
/posts |
|
content/posts/posts-1.en.md |
foo |
/posts/post-1 |
content/posts/posts-1.de.md |
foo |
/posts/post-1 |
content/posts/posts-2.en.html |
bar |
/posts/post-2 |
content/posts/posts-2.de.html |
bar |
/posts/post-2 |
没有文件支撑的页面
Page 对象上的 Path 方法总会有返回值,无论该页面是否由文件支撑。
content/
└── posts/
└── post-1.md <-- front matter: tags = ['hugo']构建站点时:
public/
├── posts/
│ ├── post-1/
│ │ └── index.html .Page.Path = /posts/post-1
│ └── index.html .Page.Path = /posts
├── tags/
│ ├── hugo/
│ │ └── index.html .Page.Path = /tags/hugo
│ └── index.html .Page.Path = /tags
└── index.html .Page.Path = /完整示例:URL 会变,逻辑路径不变
测试站的 content/posts/post-1.md 里写了 slug = "first-post",模板直接打印两种「路径」:
<p>.Path = {{ .Path }}</p>
<p>.RelPermalink = {{ .RelPermalink }}</p>实测渲染结果(baseURL = 'https://example.org/'):
<p>.Path = /posts/post-1</p>
<p>.RelPermalink = /posts/first-post/</p>实测汇总(同一站点):
| 渲染的页面 | .Path |
对应 URL |
|---|---|---|
/posts/first-post/(front matter slug = "first-post") |
/posts/post-1 |
/posts/first-post/ |
/posts/post-2/ |
/posts/post-2 |
/posts/post-2/ |
/posts/(section) |
/posts |
/posts/ |
/docs/guide/(section) |
/docs/guide |
/docs/guide/ |
/tags/alpha/(term 页) |
/tags/alpha |
/tags/alpha/ |
/zh/posts/post-1/(中文版) |
/posts/post-1 |
/zh/posts/post-1/ |
你应当看到什么:第一行与第六行最关键——slug 与语言前缀都改变了 URL,.Path 岿然不动。所以不要把 .Path 当 URL 用,也不要用它去拼链接。
返回值边界(实测)
| 情况 | 结果 | 是否报错 |
|---|---|---|
| 首页 | / |
否 |
| section 页 | /posts、/docs/guide(无尾斜杠) |
否 |
| 常规页面 | /posts/post-2(无扩展名、无尾斜杠) |
否 |
| taxonomy / term 页 | /tags、/tags/alpha |
否 |
设了 slug / url |
值不变(实测 /posts/first-post/ 的 .Path 仍是 /posts/post-1) |
否 |
| 多语言 | 各语言同名页面返回相同值(实测中英文 post-1 均为 /posts/post-1) |
否 |
| 返回类型 | string,始终以 / 开头 |
否 |
| 拿它当 URL 拼链接 | 会得到 404(例如 /posts/post-1 未必存在) |
否(页面照常构建) |
更多排查入口见故障排查。