命令 on Hugo 中文文档

hugo

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

hugo 是主命令，用来构建项目。Hugo 是用 Go 编写的快速、灵活的静态站点生成器（static site generator）。不带任何子命令直接执行 hugo，就是一次完整构建。

hugo build

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

hugo build 是父命令 hugo 的子命令，用来构建项目。它是主命令的显式写法：不写子命令时直接执行 hugo 同样会构建项目，两者行为一致，区别只在于书写方式。在脚本或文档中需要明确表达「构建」这一动作时，写成 hugo build 更清楚。

hugo server

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

hugo server 是父命令 hugo 的子命令，用来启动内置的 Web 服务器。Hugo 自带的服务器会一边构建、一边把项目提供出去；它的性能很好，但毕竟是一个选项有限的服务器，主要用于本地预览，而不是生产环境托管。

hugo server trust

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

hugo server trust 是 hugo server 的子命令，作用是把本地 CA 证书安装到系统信任库中。

用法

hugo server trust [flags] [args]

它属于 hugo server 命令：服务器在用 --tlsAuto 生成并启用本地受信任证书时，会创建一套本地 CA。只有在操作系统的信任库里登记过这套 CA，浏览器才会把服务器提供的 HTTPS 证书当作可信证书，从而不再弹出安全警告。本命令做的正是这一步登记工作。

hugo new

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

hugo new 是父命令 hugo 的子命令，用来创建新内容。它会新建一个内容文件，并自动写入日期与标题；具体创建哪一类文件，则由你提供的路径来推断。

用法

hugo new 自身不完成创建动作，而是把工作交给它的子命令：

hugo new content

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

hugo new content 是 hugo new 的子命令，用来创建新的内容文件。它会自动填入日期与标题，并根据你给出的路径推断要创建哪一类文件；也可以用 -k KIND 显式指定种类。如果主题或项目里提供了原型（archetype），新建的文件就会按原型生成。

hugo new project

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

hugo new project 是 hugo new 的子命令，用来在指定路径创建一个新项目。它会按所选的文件格式生成项目配置，并把站点所需的基本目录结构准备好，之后就可以直接在这个项目里构建站点。

hugo new theme

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

hugo new theme 是 hugo new 的子命令，用于新建主题。它会把主题骨架写入当前项目的 themes/ 目录，生成的主题可以直接使用，并附带模板示例与示例内容，方便在此基础上继续改造。

hugo config

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

hugo config 显示当前项目最终生效的配置，既包括 Hugo 的默认值，也包括你在配置文件、配置目录、命令行参数与环境变量中写入的自定义值。排查配置是否被正确覆盖时，它比直接阅读配置文件更可靠。

hugo config mounts

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

hugo config mounts 是 hugo config 的子命令，用于打印项目最终生效的文件挂载（mount）配置。挂载把内容、资源、模板等目录映射到 Hugo 的各个组件上，除了在站点配置里书写，主题与模块也会注入自己的挂载，因此最终结果往往和配置文件里看到的不完全一致。

hugo env

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

hugo env 显示 Hugo 的版本与环境信息。它输出的内容比 hugo version 更详细，除了版本号，还会列出构建时所用的 Go 版本，以及扩展版（extended）、部署（deploy）等编译时开关是否启用。提交缺陷报告或排查“同一份模板在不同机器上行为不同”时，先贴出它的输出。

hugo version

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

hugo version 显示当前 Hugo 的版本号。输出中还会带上编译进该二进制的相关信息，例如是否为扩展版，这些信息在提交缺陷报告时同样有用。需要更完整的环境明细时，改用 hugo env。

hugo list

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

hugo list 是列出站点内容的父命令。它本身不执行任何列出动作，必须搭配一个子命令使用，例如 hugo list drafts。

用法

hugo list [command] [flags]

直接运行 hugo list 而不带子命令不会输出内容列表，Hugo 会提示需要一个子命令。

hugo list all

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

hugo list all 是 hugo list 的子命令，用于列出站点的全部内容，不论其状态如何，草稿、未来内容与已过期内容都会被包含进来。需要做内容盘点或排期检查时，它比逐个状态筛选更省事。

hugo list drafts

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

hugo list drafts 是 hugo list 的子命令，用于列出草稿内容。凡是在 front matter 中设置了 draft = true 的内容页，都会被它筛选出来。默认构建不会渲染草稿，因此在发布前用它核对是否有内容仍处于草稿状态，是很常见的做法。

hugo list expired

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

hugo list expired 是 hugo list 的子命令，用于列出过期日期已经过去的内容。Hugo 依据内容前置元数据中的时间字段（例如 expiryDate）判断一个页面是否过期：过期页面在正常构建中不再发布，但源文件仍然留在内容目录里，这条命令就是把它们找出来的手段，适合在内容巡检或上线前检查时使用。

hugo list future

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

hugo list future 是 hugo list 的子命令，用于列出发布日期位于将来的内容。Hugo 依据内容前置元数据中的时间字段（例如 publishDate）判断一个页面是否属于未来内容：这类页面的发布时间还没到，因此在正常构建中不会发布，但作者往往已经写好并放在内容目录里。做发布排期、核对待上线篇目时，这条命令比手工翻文件更可靠。

hugo list published

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

hugo list published 是 hugo list 的子命令，用于列出已发布的内容，也就是既不是草稿，也没有尚未来临的发布日期、也没有已经过去的过期日期的那些页面。它给出的正是正常构建时会出现在站点上的篇目，因此常用来在发布前确认清单，或者核对某个文件为什么没有出现在线上。

hugo convert

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

hugo convert 是用于转换前置元数据格式的父命令。它把内容目录里每个文件的前置元数据改写成另一种格式，便于在 YAML、TOML 与 JSON 之间迁移：例如从其他静态站点生成器搬过来之后，想让全站统一使用 TOML 前置元数据，就可以用它批量处理，而不必手工逐个文件改写。

hugo convert toJSON

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

hugo convert toJSON 是 hugo convert 的子命令，用于把内容目录中所有文件的前置元数据都改为 JSON 格式。JSON 前置元数据以花括号包裹，机器读取方便，适合由程序生成或批量处理的站点；把整站统一到一种格式，也能避免同一项目里 TOML、YAML、JSON 三种写法混用带来的混乱。

hugo convert toTOML

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

hugo convert toTOML 是 hugo convert 的子命令，用于把内容目录中所有文件的前置元数据都改为 TOML 格式。TOML 前置元数据以加号组成的分隔行包裹，也是 Hugo 项目配置常见的书写方式；如果站点配置用 TOML，把内容的前置元数据也统一成 TOML，全项目的写法会更为一致。

hugo convert toYAML

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

hugo convert toYAML 是 hugo convert 的子命令，用于把内容目录中所有文件的前置元数据都改为 YAML 格式。YAML 前置元数据以三个连字符组成的分隔行包裹，可读性好、嵌套结构表达自然，是许多站点与主题文档默认采用的写法；从其他静态站点生成器迁移过来时，这个子命令最常被用到。

hugo deploy

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

hugo deploy 把项目部署到云端提供商。它按照站点配置 deployment 区段中声明的目标，把构建产物上传到对应的对象存储或托管服务，并可选地清理多余文件、刷新 CDN 缓存。相比把上传步骤写进脚本，这种方式的差异由 Hugo 自己比对，只上传有变化的文件，因此重复发布更快。

hugo gen

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

hugo gen 是生成类辅助命令的父命令，用于产出命令行文档、man 手册页以及 Chroma 语法高亮样式表。它本身不执行任何生成动作，必须搭配一个子命令使用，例如 hugo gen doc。

hugo gen chromastyles

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

hugo gen chromastyles 是 hugo gen 的子命令，按给定的样式名生成 Chroma 代码高亮器所需的 CSS 样式表。当配置中的 markup.highlight.noClasses 被禁用（也就是不再为高亮代码输出内联样式）时，站点必须引入这张样式表，否则高亮代码不会有任何颜色。

hugo gen doc

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

hugo gen doc 是 hugo gen 的子命令，为 Hugo 命令行界面生成 Markdown 文档。它为每个命令生成一个 Markdown 文件，并写好适合在 Hugo 中渲染的 front matter，因此输出结果可以直接放进文档站点的内容目录。

hugo gen man

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

hugo gen man 是 hugo gen 的子命令，为 Hugo 命令行界面自动生成保持最新的 man 手册页。默认情况下，它会在当前目录下的 man/ 目录中创建手册页文件。

生成的 man 手册页适合安装到系统的 man 路径中，之后就能用 man hugo 之类的命令在终端里查阅离线文档。

hugo import

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

hugo import 是导入类命令的父命令，用于把其他静态站点生成器的项目导入为 Hugo 项目。它本身不执行导入，必须搭配一个子命令使用，例如 hugo import jekyll jekyll_root_path target_path。

目前该父命令下收录的子命令是 hugo import jekyll，用于从 Jekyll 站点导入。

hugo import jekyll

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

hugo import jekyll 是 hugo import 的子命令，用于从 Jekyll 项目导入站点。它需要两个路径参数：先是 Jekyll 站点的根目录，再是写入导入结果的目标目录，例如 hugo import jekyll jekyll_root_path target_path。

导入会把 Jekyll 的内容与配置转换为 Hugo 可以使用的形式，省去逐篇迁移文章的重复劳动。

hugo mod

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

hugo mod 是管理模块的一组辅助命令的父命令，用于维护项目依赖图中的 Hugo Modules。它本身不执行具体操作，必须搭配一个子命令使用，例如 hugo mod tidy。

这里的多数操作都要求系统上安装了 Go（版本不低于 Go 1.12）以及相应的版本控制系统客户端（通常是 Git）。如果只使用 /themes 目录中的模块，或者已经通过 hugo mod vendor 把它们 vendor 到本地，则不需要这些依赖。

hugo mod clean

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

hugo mod clean 是 hugo mod 的子命令，用于删除当前项目的 Hugo 模块（Module）缓存。Hugo 在解析模块依赖时会把取到的模块放进缓存目录，当缓存损坏、版本对不上，或者希望依赖重新取一遍时，可以用它把缓存清掉。

hugo mod get

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

hugo mod get 是 hugo mod 的子命令，用于解析当前 Hugo 项目里的模块（Module）依赖。它既可以为某个模块取回可用的最新版本，也可以锁定到指定版本，或者一次性更新全部直接依赖、直接与间接依赖。

hugo mod graph

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

hugo mod graph 是 hugo mod 的子命令，用于打印模块（Module）依赖关系图，并附带模块状态信息，例如是否被禁用、是否来自 vendor。排查“某个依赖究竟从哪来”“版本为什么和预期不一致”这类问题时，它是第一步要看的东西。

hugo mod init

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

hugo mod init 是 hugo mod 的子命令，用于把当前项目初始化为一个 Hugo Module（模块）。执行后项目会具备作为模块被引用、以及引用其他模块的条件，是使用 Hugo Modules 管理主题与共享资源的第一步。

hugo mod npm

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

hugo mod npm 是 hugo mod 的子命令，本身是一组与 npm（Node 包管理器）相关的辅助命令的入口。当项目里的 Hugo 模块带有自己的 Node.js 依赖时，这些辅助命令负责把依赖整理成可直接安装的形式，而不必逐个模块手工安装。

hugo mod npm pack

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

hugo mod npm pack 是 hugo mod 的子命令，也是 hugo mod npm 目前唯一的子命令。它把所有 Hugo 模块（Module）里声明的 Node.js 依赖合并到一个名为 packages/hugoautogen 的 npm workspace 中，省去手工逐个模块安装依赖的麻烦。

hugo mod tidy

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

hugo mod tidy 是 hugo mod 的子命令，用于删除 go.mod 与 go.sum 中不再被使用的条目。项目长期演进、模块增删之后，这两个文件里往往会留下已移除依赖的残迹，执行一次整理可以让依赖声明重新与实际情况对齐。

hugo mod vendor

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

hugo mod vendor 是 hugo mod 的子命令，用于把当前项目依赖的所有 Hugo 模块（Module）集中复制到项目根目录下的 _vendor 目录。一个模块被 vendor 之后，Hugo 就从 _vendor 目录里查找它的依赖，因此构建过程不再需要访问网络。这在离线环境、构建服务器上无法直连模块仓库，或者希望把依赖固定下来的场合都很有用。

hugo mod verify

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

hugo mod verify 是 hugo mod 的子命令，用来校验当前模块的依赖：这些依赖保存在本地已下载的源码缓存里，命令会检查它们自下载以来有没有被修改过。如果校验没有通过，可以加上 --clean 把未通过校验的依赖缓存删掉，之后再重新取回这些依赖。

hugo completion

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

hugo completion 用来为指定的 shell 生成 hugo 命令的自动补全脚本。它本身不输出补全结果，而是按子命令决定生成哪一种 shell 的脚本：bash、fish、powershell 或 zsh。生成脚本之后，把它交给对应的 shell 执行或加载，输入 hugo 及其子命令、选项时就能用补全键（通常是 Tab）自动补全。每个子命令的帮助信息里都写明了该 shell 下如何使用生成的脚本。

hugo completion bash

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

hugo completion bash 生成 bash 的自动补全脚本。把脚本交给 bash 执行之后，输入 hugo 及其子命令或选项时就能用 Tab 键补全。生成的脚本依赖 bash-completion 软件包：如果系统里还没有安装，可以用操作系统的包管理器装一个。

hugo completion fish

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

hugo completion fish 生成 fish 的自动补全脚本。fish 的用法与其他 shell 略有不同：它的补全逻辑用 fish 脚本书写，可以直接用管道交给本会话执行，也可以写入 fish 约定的补全目录，让之后的每个会话自动加载。

hugo completion powershell

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

hugo completion powershell 生成 PowerShell 的自动补全脚本。脚本内容是一段 PowerShell 代码，因此在当前会话中加载时需要先用 Out-String 把它转成字符串，再用 Invoke-Expression 执行；希望长期生效，则把这段输出写进 PowerShell 的配置文件。

hugo completion zsh

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

hugo completion zsh 生成 zsh 的自动补全脚本。zsh 的补全体系依赖 compinit，并从 fpath 数组列出的目录里查找补全函数，函数名以 _ 开头且与命令同名，所以生成的脚本要保存为 _hugo。