os.FileExists
报告文件或目录是否存在。
这一页解决什么问题
模板要按「有没有这个文件」分支时用它:站点根下有没有 README.md、内容目录里有没有那张配图、某个可选的数据文件是否提供。os.FileExists 只回答存在与否,不去读内容,因此比先 os.ReadFile 再判断要安全得多——后者在路径不存在时只会给你一个空字符串。
什么时候用,什么时候别用
该用:
- 可选文件的存在性判断(有就渲染,没有就跳过);
- 需要「目录也算存在」时(本函数对目录返回
true)。
别用:
- 想读内容 → 用
os.ReadFile(注意:传目录会让构建失败); - 想要大小、修改时间等元信息 → 用
os.Stat; - 想列出目录里的条目 → 用
os.ReadDir; - 想取得可处理的资源对象(图片、SCSS)→ 用
resources.Get:它返回nil而不是布尔值,可以直接with。
用法
os.FileExists 函数先尝试相对于项目目录的根解析路径。如果找不到匹配的文件或目录,它会尝试相对于 contentDir 解析路径。路径开头的分隔符(/)是可选的。
目录结构如下:
tree
content/
├── about.md
├── contact.md
└── news/
├── article-1.md
└── article-2.md该函数返回以下值:
go-html-template
{{ fileExists "content" }} → true
{{ fileExists "content/news" }} → true
{{ fileExists "content/news/article-1" }} → false
{{ fileExists "content/news/article-1.md" }} → true
{{ fileExists "news" }} → true
{{ fileExists "news/article-1" }} → false
{{ fileExists "news/article-1.md" }} → true完整示例(实测)
在项目根下放置 README.md,并准备上面的 content/ 目录结构:
layouts/_partials/has-file.htmlgo-html-template
[{{ fileExists "news/article-1.md" }}]|[{{ fileExists "news/article-1" }}]|[{{ fileExists "nope" }}]Hugo 0.167.0 实测输出:
[true]|[false]|[false]你应当看到什么:news/article-1.md 存在(路径可以先相对于项目根解析,再相对于 contentDir),所以是 true;漏掉扩展名的 news/article-1 是 false;完全不存在的路径也是 false,不报错。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'zh-CN'),Windows;项目结构与上游示例一致。
| 输入 | 结果 | 是否报错 |
|---|---|---|
"content"、"content/news"(目录) |
true——目录也算存在 |
否 |
"content/news/article-1"(缺扩展名) |
false |
否 |
"content/news/article-1.md" |
true |
否 |
"news"、"news/article-1.md"(相对 contentDir) |
true |
否 |
"nope"(完全不存在) |
false |
否 |
"/README.md"(带前导斜杠) |
true——前导斜杠可选 |
否 |
| 返回类型 | bool,永远不是 nil |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 判断「文件存在」通过了,读出来却是目录 | 目录也返回 true(实测 "content" 为 true) |
需要区分类型就用 os.Stat 看 .IsDir |
| 没报错但结果不对 | 明明有文件却返回 false |
漏写扩展名(实测缺 .md 就是 false),或路径基准不对 |
补全文件名;记住路径先按项目根、再按 contentDir 解析 |
| 报错看不懂 | 想确认存在就调用 os.ReadFile,结果拿到空字符串 |
该函数对不存在的路径返回空串、不报错 | 先 fileExists 判断,再读 |
更多排查入口见故障排查。