File
返回给定页面的文件信息;若该页面没有对应文件,则返回 nil。
这一页解决什么问题
File 返回页面背后的文件信息对象(路径、文件名、扩展名、所在 section 等)。给页面找同目录资源、按文件组织内容、在文件名里编码信息,都从这里入手;同时它也是最容易踩 nil 的方法之一——不是每个页面都有文件。
什么时候用,什么时候别用
该用:
- 需要文件路径或文件名(例如把
content/news/2024/a.md的目录结构映射成 URL 或分类); - 判断包的类型:
.File.ContentBaseName(包目录名)、.File.IsContentAdapter; - 配合
.Resources处理叶子包里的资源。
别用:
- 想拿页面 URL → 用
.RelPermalink/.Permalink。.File.Path是内容目录内的相对路径,且 Windows 上是反斜杠; - 想判断页面种类 → 用
Kind/IsPage; - 不加判断地访问
.File.xxx:顶层 section 页(无_index.md时)、分类法页、术语页都没有文件。
用法
默认情况下,并非所有页面都有对应的文件,包括顶层 section 页、分类法页与术语页。顾名思义,文件不存在时你无法取得文件信息。
要让上述某类页面拥有对应文件,请在相应目录中创建 _index.md 文件。例如:
content/
└── books/
├── _index.md <-- the top-slevel section page
├── book-1.md
└── book-2.md方法
在 File 对象上使用这些方法。
BaseFileName- (
string)文件名,不含扩展名。go-html-template{{ with .File }} {{ .BaseFileName }} {{ end }} ContentBaseName- (
string)如果该页面是分支包或叶子包,则返回所在目录的名称,否则返回TranslationBaseName。go-html-template{{ with .File }} {{ .ContentBaseName }} {{ end }} Dir- (
string)文件路径中去掉文件名后的部分,相对于content目录。go-html-template{{ with .File }} {{ .Dir }} {{ end }} Ext- (
string)文件扩展名。go-html-template{{ with .File }} {{ .Ext }} {{ end }} Filename- (
string)文件的绝对路径。go-html-template{{ with .File }} {{ .Filename }} {{ end }} IsContentAdapter- (
bool)报告该文件是否为内容适配器。go-html-template{{ with .File }} {{ .IsContentAdapter }} {{ end }} LogicalName- (
string)文件名。go-html-template{{ with .File }} {{ .LogicalName }} {{ end }} Path- (
string)文件路径,相对于content目录。go-html-template{{ with .File }} {{ .Path }} {{ end }} Section- (
string)该文件所在顶层 section 的名称。go-html-template{{ with .File }} {{ .Section }} {{ end }} TranslationBaseName- (
string)文件名,不含扩展名与语言标识符。go-html-template{{ with .File }} {{ .TranslationBaseName }} {{ end }} UniqueID- (
string).File.Path的 MD5 哈希值。go-html-template{{ with .File }} {{ .UniqueID }} {{ end }}
示例
假设多语言项目的内容结构如下:
content/
├── news/
│ ├── b/
│ │ ├── index.de.md <-- leaf bundle
│ │ └── index.en.md <-- leaf bundle
│ ├── a.de.md <-- regular content
│ ├── a.en.md <-- regular content
│ ├── _index.de.md <-- branch bundle
│ └── _index.en.md <-- branch bundle
├── _index.de.md
└── _index.en.md在英文站点中:
| 普通内容 | 叶子包 | 分支包 | |
|---|---|---|---|
| BaseFileName | a.en | index.en | _index.en |
| ContentBaseName | a | b | news |
| Dir | news/ | news/b/ | news/ |
| Ext | md | md | md |
| Filename | /home/user/… | /home/user/… | /home/user/… |
| IsContentAdapter | false | false | false |
| LogicalName | a.en.md | index.en.md | _index.en.md |
| Path | news/a.en.md | news/b/index.en.md | news/_index.en.md |
| Section | news | news | news |
| TranslationBaseName | a | index | _index |
| UniqueID | 15be14b… | 186868f… | 7d9159d… |
防御式编码
站点上有些页面可能没有对应文件,例如:
- 顶层 section 页
- 分类法页
- 术语页
没有对应文件时,一旦访问 .File 属性,Hugo 就会抛出错误。为此要编写防御式代码,先检查文件是否存在:
{{ with .File }}
{{ .ContentBaseName }}
{{ end }}完整示例:同一个模板打印三种页面的文件信息
最小站点:content/docs/guide/alpha.md(普通页面)、content/docs/guide/bundle/index.md(叶子包)、/tags/hugo/(术语页,没有对应文件)。模板放在 layouts/_default/single.html:
{{ with .File }}
<p>{{ .Path }}|{{ .BaseFileName }}|{{ .ContentBaseName }}|{{ .Dir }}|{{ .Ext }}|{{ .LogicalName }}|{{ .Section }}</p>
{{ else }}
<p>该页面没有对应文件</p>
{{ end }}hugo --source <站点目录> --ignoreCache 构建后(Windows):
<p>docs\guide\alpha.md|alpha|alpha|docs\guide\|md|alpha.md|docs</p>
<p>docs\guide\bundle\index.md|index|bundle|docs\guide\bundle\|md|index.md|docs</p>术语页 /tags/hugo/ 用同一个模板渲染,输出:
<p>该页面没有对应文件</p>你应当看到什么:普通页面的 BaseFileName 与 ContentBaseName 同为 alpha;叶子包不同——BaseFileName 是 index,ContentBaseName 是目录名 bundle。路径分隔符在 Windows 上是 \(上游已说明),不要把它当 URL 用。术语页的 .File 为 nil,with 直接走兜底分支。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,Windows;结构见上,另有 en/zh 双语页面。
| 情况 | 结果 | 是否报错 |
|---|---|---|
普通页面、有 _index.md 的 section 页 |
返回文件信息对象 | 否 |
分类法页、术语页(实测)、无 _index.md 的顶层 section 页(上游说明) |
nil;不加判断就访问字段会报错 |
否(访问字段时才报错) |
叶子包的 .ContentBaseName |
包目录名(bundle) |
否 |
译文页面(alpha.zh.md) |
.BaseFileName = alpha.zh、.LogicalName = alpha.zh.md、.TranslationBaseName = alpha |
否 |
.Path / .Dir / .Filename 的分隔符 |
Windows 为 \,其他系统为 / |
否 |
.UniqueID |
.File.Path 的 MD5 哈希 |
否 |
| 返回类型 | hugolib.fileInfo(可能为 nil) |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 构建报错 | 分类法页 / 术语页上访问 .File.Path 报错 |
这些页面没有对应文件,.File 为 nil |
一律用 {{ with .File }} 包起来(见上游「防御式编码」) |
| 没报错但结果不对 | 用 .File.Path 拼 URL,结果带反斜杠 |
它是操作系统路径,不是 URL | URL 用 .RelPermalink |
| 没报错但结果不对 | 叶子包与普通页面的 BaseFileName 混用 |
叶子包文件名固定是 index,页面名在 ContentBaseName |
需要「页面名」时用 .ContentBaseName |
| 没报错但结果不对 | 多语言项目的文件名与预期不符 | 语言后缀参与 BaseFileName / LogicalName |
需要不含语言后缀的名字时用 TranslationBaseName |
更多排查入口见故障排查。