故障排查 on Hugo 中文文档

常见问题

Thu, 01 Oct 2026 00:00:00 +0800

关于这份常见问题

Hugo 的论坛是活跃的用户与开发者社区，两万多个主题中往往已经有人回答过你的问题；中文提问请用官方论坛的中文分类。提问之前，请先阅读论坛的求助指南。下面列出新用户最常问到的若干问题。

提示某个功能不可用

当你在所安装的版本（edition）中使用它并不提供的功能时，Hugo 会抛出这个错误：

this feature is not available in this edition of Hugo

解决办法是安装另一个版本，详见安装。

审计

Thu, 01 Oct 2026 00:00:00 +0800

为什么要做审计

有些问题不会在构建时报错，却会出现在正式发布的站点上。因此在最终构建之前，应当先对输出目录做一次审计。先以「保留注释 + 显示缺失翻译占位符」的方式构建，再扫描发布目录：

弃用说明

Thu, 01 Oct 2026 00:00:00 +0800

什么是弃用

当一个项目宣布某项内容「弃用」（deprecate）时，它是在告诉用户三件事：

不要再使用「甲」了。
请改用「乙」。
我们会在将来某个时间点移除「甲」。

常见的弃用原因包括：

检查与调试

Thu, 01 Oct 2026 00:00:00 +0800

检查数据结构

用 debug.Dump 函数检查数据结构：

<pre>{{ debug.Dump .Params }}</pre>

渲染结果类似下面的内容：

{
  "date": "2023-11-10T15:10:42-08:00",
  "draft": false,
  "iscjklanguage": false,
  "lastmod": "2023-11-10T15:10:42-08:00",
  "publishdate": "2023-11-10T15:10:42-08:00",
  "tags": [
    "foo",
    "bar"
  ],
  "title": "My first post"
}

检查简单值

用 printf 函数把结果渲染到页面，或用 warnf 函数输出到控制台，可以检查简单的数据结构。下面的布局字符串同时显示值与数据类型：

日志

Thu, 01 Oct 2026 00:00:00 +0800

命令行

用 --logLevel 命令行标志启用控制台日志。Hugo 有四个日志级别，级别越高，显示的消息越详细：

error

只显示错误消息。

hugo build --logLevel error

warn

显示警告与错误消息。

hugo build --logLevel warn

info

显示信息、警告与错误消息。

hugo build --logLevel info

debug

显示调试、信息、警告与错误消息。

hugo build --logLevel debug

说明如果没有用 --logLevel 指定日志级别，警告与错误始终会显示。

性能

Thu, 01 Oct 2026 00:00:00 +0800

Hugo 本身很快，拖慢构建的往往是外部因素与低效的模板。下面从两个方向入手：减少构建过程中不必要的系统开销，以及减少模板的重复执行。

病毒扫描

病毒扫描软件是系统防护的必要组成部分，但对 Hugo 这类频繁读写磁盘的程序来说，性能影响可能非常严重。例如使用 Microsoft Defender Antivirus 时，某些站点的构建时间可能增加 400% 甚至更多。