常见问题
新用户最常遇到的问题:页面不显示、首页 404、局部模板不渲染、构建输出不一致等,每个都给出原因、确认方法和修法。
开始之前,你需要
- 手头有一个能构建、或能复现问题的 Hugo 项目
- 知道项目根目录在哪里,也能打开终端
读完之后你能
- 用「症状 → 小节」的方式快速命中自己的问题,而不是从头读到尾
- 独立解决页面不发布、首页 404、局部模板不渲染这三类高频问题
- 知道每个「为什么」要链到哪一页去看完整规则
Hugo 的论坛是活跃的用户与开发者社区,两万多个主题中往往已经有人回答过你的问题;中文提问请用官方论坛的中文分类。提问之前,请先阅读论坛的求助指南。下面列出新用户最常问到的若干问题。
先按症状分诊
| 你看到的 | 先读哪一节 |
|---|---|
| 报错说某个功能不可用 | 提示某个功能不可用 |
| 打开首页是「Page Not Found」 | 访问首页时显示「Page Not Found」 |
| 写好的文章在站点里找不到 | 某个页面没有被发布 |
| 某个栏目下看不到子页面 | 看不到某个页面的下级页面 |
| 分部模板 / 局部模板输出不对 | 局部模板没有按预期渲染 |
| 同一个页面出现两份、或输出每次不一样 | 每次构建的输出为什么不一致 |
改了文件但 hugo server 没反应 |
开发服务器为什么检测不到文件变化 |
| 短代码、分页、变量赋值的写法拿不准 | 见下文对应小节 |
下面每条都按「为什么 → 怎么确认 → 怎么修」写。
提示某个功能不可用
当你在所安装的版本(edition)中使用它并不提供的功能时,Hugo 会抛出这个错误:
this feature is not available in this edition of Hugo为什么:Hugo 有多个版本(edition),例如标准版与 extended 版,某些功能只在其中一部分版本里编译进去。这不是配置写错,而是二进制本身没有这个能力。
怎么确认:先看版本行里有没有 extended 字样:
hugo versionhugo v0.167.0+extended windows/amd64 ...怎么修:安装另一个版本,详见安装。
访问首页时显示「Page Not Found」
请检查 content/_index.md 文件:
draft是否被设为true?date是否在未来?publishDate是否在未来?expiryDate是否已经过去?
为什么:首页也是一个普通页面,同样受这组字段约束;只要有一项命中,Hugo 就按「不发布」处理,而不是报错。
怎么确认:
hugo list all # 列出 Hugo 实际认到的所有内容文件
hugo list drafts # 只列草稿
hugo list future # 只列日期还在未来的页面
hugo list expired # 只列已经过期的页面怎么修:只要有一项答案为「是」,就修改字段值,或使用 --buildDrafts、--buildFuture、--buildExpired 中的一个命令行标志。字段的完整规则见基本用法。
某个页面没有被发布
请检查 content/section/page.md 或 content/section/page/index.md 文件,判断标准与上一个问题相同:draft、date、publishDate、expiryDate。
怎么确认:hugo list all 里能查到它,说明 Hugo 读到了文件、只是被规则拦下;若 hugo list all 里也没有它,问题不在发布时间,而在文件位置或文件名(例如放进了 content/ 之外,或后缀不是 .md)。
怎么修:同样,修改字段值,或使用 --buildDrafts、--buildFuture、--buildExpired。
看不到某个页面的下级页面
你可能用了 index.md,而这里应当是 _index.md。
为什么:含 index.md 的目录是leaf bundle(叶子包),它自己不向下公开子页面;含 _index.md 的目录是branch bundle(分支包),才能承载子页面列表。详见页面包。
怎么确认:列出该目录的文件名,确认是 index.md 还是 _index.md;再对照 hugo list all 的输出,缺的页面通常就是这一层。
index.md 与 _index.md 有什么区别
含 index.md 的目录是leaf bundle,含 _index.md 的目录是branch bundle。详见页面包。
简单记法:叶子包放一篇内容和它的资源,分支包放一组页面。
局部模板没有按预期渲染
调用局部模板(partial)时,可能忘记传入所需的上下文。例如:
{{/* incorrect */}}
{{ partial "pagination.html" }}
{{/* correct */}}
{{ partial "pagination.html" . }}为什么:局部模板不会自动继承调用者的context(上下文),第二个参数就是它拿到的「.」。不传时,模板内部的 .Paginator 一类字段全部取不到值。
怎么确认:把调用临时改成 {{ printf "%T" . }} 之类,或在局部模板首行加一句 <pre>{{ debug.Dump . }}</pre> 打印实际拿到的数据,做法见检查与调试。若模板内部报「nil pointer」或输出空白,基本就是这个原因。
怎么修:补上第二个参数;需要传递附加数据时用字典:
{{ partial "pagination.html" (dict "page" . "size" 5) }}给变量赋值时 := 与 = 有什么区别
用 := 初始化变量,用 = 给此前已经初始化的变量赋值。详见 text/template 关于变量的说明。
为什么::= 声明并赋值,= 只赋值。对没有声明过的变量用 = 会直接报错,而不是静默失败——这条报错信息通常很直白,看到 undefined variable 就往这里想。
列表页分页后页面集合没有按条件过滤
很可能在同一页面上多次调用了 Paginate 或 Paginator 方法。详见分页。
为什么:分页状态与「当前这次分页的页面集合」绑定。同一页面第二次调用会拿到另一套状态,导致分页结果和过滤条件对不上。
怎么修:把分页结果先赋给一个变量,后续复用这个变量:
{{ $paginator := .Paginate (where .Pages "Section" "posts") }}
{{ range $paginator.Pages }}{{ .Title }}{{ end }}为什么短代码有两种调用方式
如果短代码模板本身,或开始与结束标签之间的内容包含 Markdown,使用 {{% shortcode %}} 写法;否则使用 {{< shortcode >}} 写法。详见短代码的写法。
为什么:两种写法决定了执行顺序。Markdown 写法({{% … %}})在 Markdown 渲染器之前执行,因此它的 .Inner 是原始 Markdown,里面的标题也会进目录;标准写法({{< … >}})在 Markdown 渲染器之后执行,.Inner 是未渲染的文本,需要手动 markdownify,其中的标题不会进目录。
怎么确认:如果短代码里的 Markdown 原样显示成一堆符号,说明用了标准写法;如果短代码里的 HTML 被转义成可见标签,说明用了 Markdown 写法。
可以用环境变量控制配置吗
可以。详见配置。
怎么确认:用 hugo config 查看合并后的最终结果,确认环境变量是否真的生效。
每次构建的输出为什么不一致
最常见的原因是页面冲突(两个页面发布到同一路径)以及并发带来的影响。用 --printPathWarnings 命令行标志检查页面冲突;如果怀疑是并发问题,请在论坛发帖说明。
怎么确认:
hugo --ignoreCache --printPathWarnings输出里出现重复目标路径的行,就是冲突点。两个页面发布到同一路径时,谁后写谁留下,于是「同一份源码、两次构建、不同结果」。
怎么修:把冲突的两个源文件改成不同路径(常见于 content/a/b.md 与 content/a/b/index.md 并存),或删掉多余的那一个。
开发服务器为什么检测不到文件变化
在默认配置下,以下情形中 Hugo 的文件监视器可能无法检测到文件变化:
- 在 Windows Subsystem for Linux(WSL/WSL2)中运行 Hugo,而项目文件位于 Windows 分区;
- 在本地运行 Hugo,而项目文件位于可移动驱动器;
- 在本地运行 Hugo,而项目文件位于通过 NFS、SMB 或 CIFS 协议访问的存储服务器。
为什么:默认方案依赖操作系统提供的原生文件系统事件;跨分区、跨网络的挂载点往往不产生这些事件,或者事件不能跨边界传回 Hugo。
怎么修:这些情况下请改用 --poll 命令行标志,以轮询代替原生文件系统事件。例如每 700 毫秒轮询一次项目文件:--poll 700ms。
hugo server --poll 700ms你应当看到什么:改一个内容文件并保存,终端应在 1 秒内出现重新构建的日志;页面自动刷新。若仍无反应,先确认编辑的是项目目录内的文件,再逐步减小轮询间隔。
页面的 Store 里为什么缺少某个值
Store 方法为该页面建立持久的数据结构,用于存放和操作键值数据。这些值通常在短代码模板、由短代码调用的局部模板或渲染钩子模板中设置;在 Hugo 渲染页面内容之前,它们都不是确定值。
为什么:父模板先于页面内容渲染。父模板去取 Store 里的值时,短代码可能还没执行,键自然还不存在。
如果需要从父模板访问已存储的值,而父模板尚未渲染页面内容,可以把返回值赋给一个无用的 noop 变量,以此触发内容渲染:
{{ $noop := .Content }}
{{ .Store.Get "mykey" }}用其他方法同样可以触发内容渲染,见下一个问题。
哪些页面方法会触发内容渲染
Page 对象上的以下方法会触发内容渲染:Content、ContentWithoutSummary、FuzzyWordCount、Len、Plain、PlainWords、ReadingTime、Summary、Truncated、WordCount。
怎么用:把不需要的返回值赋给 $noop,只为触发渲染,例如:
{{ $noop := .WordCount }}
{{ .Store.Get "mykey" }}常见坑
命令找不到
- 照抄了含
grep/which的命令却在 Windows PowerShell 里执行:改用Select-String、Get-Command; hugo list …报未知命令:旧版本可能没有该子命令,用hugo --help对照;- 在 WSL 里
hugo: command not found:WSL 是独立环境,需要单独安装 Hugo。
没有报错但结果不对
- 不在项目根目录执行:Hugo 会构建出一个空站点并正常退出,页面数为 0 却不报错。先确认当前目录下有
hugo.toml; - 只看了页面、没看列表:
hugo list all是判断「Hugo 到底有没有读到这个文件」最省事的办法; - 改了配置没生效:确认改的是项目根目录下的配置文件,再用
hugo config看合并后的结果; - 开发服务器在看旧文件:
hugo server有缓存,怀疑结果不对时用hugo --ignoreCache重新构建一次。
报错看不懂