os.ReadFile
返回文件的内容。
这一页解决什么问题
把项目里的一个文本文件原样搬进模板:README.md、LICENSE、一段 SVG、一个 CSV 片段。os.ReadFile 返回未经解释的原始内容——这一点很关键:Markdown 不会变成 HTML,模板语法也不会被执行。
什么时候用,什么时候别用
该用:
- 内联一段原始文本(许可证、说明、SVG 标记);
- 把 Markdown 读进来后自己决定要不要渲染。
别用:
- 想让 Markdown 变成 HTML → 读出来之后还要过
transform.Markdownify; - 想处理资源(图片缩放、SCSS 编译、加指纹)→ 用
resources.Get,它返回资源对象; - 只想判断文件在不在 → 用
os.FileExists:本函数对不存在的路径返回空字符串而不报错; - 想读结构化数据 → 放进
data/目录按数据文件使用。
用法
os.ReadFile 函数先尝试相对于项目目录的根解析路径。如果找不到匹配的文件,它会尝试相对于 contentDir 解析路径。路径开头的分隔符(/)是可选的。
假设项目目录根下有一个名为 README.md 的文件:
md
This is **bold** text.以下模板代码:
go-html-template
{{ readFile "README.md" }}输出:
html
This is **bold** text.注意,os.ReadFile 返回的是原始(未经解释)内容。
完整示例(实测)
项目根下有内容为 This is **bold** text. 的 README.md,content/about.md 带前置元数据。
layouts/_partials/inline.htmlgo-html-template
[{{ readFile "README.md" }}]
[{{ readFile "content/about.md" }}]Hugo 0.167.0 实测输出(第二行的 + 与 ' 在网页里会显示为 HTML 实体):
[This is **bold** text.]
[+++
title='About'
+++
About body]你应当看到什么:第一行里 **bold** 原样出现——Markdown 没有被渲染;第二行连 +++ 前置元数据都一起读出来了,说明本函数不区分正文与元数据。
返回值边界(实测)
测量条件:Hugo 0.167.0 extended,单语言站点(locale = 'zh-CN'),Windows。
| 情况 | 结果 | 是否报错 |
|---|---|---|
文件存在(实测 "README.md") |
文件原文,逐字符返回(Markdown 标记不解释) | 否 |
文件不存在(实测 readFile "nope.md") |
""(空字符串) |
否——静默返回空串 |
带前导斜杠(实测 "/README.md") |
与不带斜杠等价 | 否 |
相对 contentDir 的路径(实测 "content/about.md") |
连同前置元数据一起返回 | 否 |
路径指向目录(实测 readFile "content") |
—— | 是,构建失败:error calling readFile: read ...\content: Incorrect function.(Windows 上的报错文案) |
| 返回类型 | string |
否 |
常见坑
| 类别 | 症状 | 真因 | 怎么修 |
|---|---|---|---|
| 没报错但结果不对 | 页面上出现 **bold** 字样 |
readFile 返回原文,不渲染 Markdown |
接 transform.Markdownify |
| 没报错但结果不对 | 文件明明不存在,页面却是空的 | 不存在的路径返回空字符串、不报错(实测) | 先用 os.FileExists 判断 |
| 报错看不懂 | error calling readFile: read …: Incorrect function. |
传入的路径是目录而不是文件 | 改成具体文件的路径;列目录用 os.ReadDir |
| 没报错但结果不对 | 相对路径读到了意外的文件 | 路径先按项目根解析,再按 contentDir 解析 |
路径尽量从项目根写全(如 content/about.md) |
更多排查入口见故障排查。