基本用法
构建、预览与发布 Hugo 站点的日常命令:每条命令给出验证方法与失败时的排查入口。
开始之前,你需要
读完之后你能
- 用
hugo build把站点发布到public/,并解释public/为什么不会自动清空、这会带来什么后果 - 用
hugo server起本地预览,知道它监视哪些目录、LiveReload 与--navigateToChanged各自解决什么问题 - 用
-D/-E/-F控制草稿、过期与将来内容是否参与构建,并能用「文件在不在public/里」验证 - 区分发布(publish)与部署(deploy),并在出错时按现象找到对应的排查页
这一页是跑通快速开始之后的日常操作手册:构建、预览、发布三件事。每条命令后面都写了「你应当看到什么」,因为 Hugo 有一个很容易让人误判的特点——命令成功不代表结果正确。
先看全局,后面再逐条展开:
| 你想做什么 | 命令 | 产出 / 现象 |
|---|---|---|
| 本地预览、边写边看 | hugo server |
终端给出本地网址(默认 http://localhost:1313/) |
| 发布成静态文件 | hugo build |
项目根目录下出现 public/,里面是完整成品 |
| 部署到线上 | 把 public/ 上传到托管平台 |
见托管与部署 |
测试安装
安装 Hugo 之后,先确认它能跑起来:
hugo version你应当看到一行以 hugo v 开头的版本信息,例如:
hugo v0.167.0+extended windows/amd64 BuildDate=2026-09-28T14:50:38Z VendorInfo=gohugoio为什么用这一条做判据:version 子命令不需要项目目录,在任何位置都能运行。所以它失败时,问题一定在安装或环境变量上,与你的项目无关——这能帮你省掉一大段排查。
失败时的两种典型情况:
- 输出
hugo: command not found(macOS/Linux)或「‘hugo’ 不是内部或外部命令」(Windows):可执行文件不在PATH里,按安装 Hugo对应平台的小节重做; - 版本号明显偏旧:本站示例以 v0.167.0 为准,旧版本缺哪些子命令、哪些配置键对不上,本页下面的「查看可用命令」会教你自己确认。
查看可用命令
查看全部可用命令与参数:
hugo help查看某个子命令的帮助,使用 --help 参数:
hugo server --help为什么这一步值得养成习惯:文档与教程都会过时,hugo help 不会——它打印的是你这台机器上真实存在的命令和默认值。hugo help 也可以写成 hugo --help 或 hugo -h。
你应当看到 Available Commands 下列出 build、server、new、config、list、gen 等子命令。如果你的列表里没有教程中写的命令,不要照抄教程,先以本机 --help 的输出为准;参数同理,hugo server --help 里会写明每个参数的默认值(例如端口默认 1313)。
构建站点
切换到项目目录后执行:
cd my-project
hugo build你应当看到两类结果,两类都满足才算构建成功:
- 终端打印一份统计表(
Pages、Static files、Total in … ms),Pages的数量与你的内容量相符; - 项目根目录下出现
public/,其中至少有index.html。
在 Windows PowerShell 里验证第 2 条:
Test-Path public/index.html输出 True 才算成功。
hugo build 会构建项目,把文件发布到 public 目录。要发布到其他目录,可以使用 --destination 参数,或在项目配置中设置 publishDir。默认值可以直接问 Hugo:
hugo config | grep -i publishdirpublishdir = 'public'(Windows PowerShell 把管道后半段换成 Select-String publishdir。)
临时换目录用 --destination,长期固定用配置项 publishDir——否则每次构建都要记得多敲一个参数,迟早会忘。
这条提醒对新手尤其重要:public/ 里装的是上一次构建的残留。你删掉一篇文章、或者把它改成草稿,public/ 里对应的旧 HTML 仍然在,上传后线上依旧能访问到它。所以判断标准是看 public/ 里的实际文件,而不是只看命令有没有报错。
草稿、将来与过期内容
你可以在内容的前置元数据中设置 draft、date、publishDate 与 expiryDate。默认情况下,满足以下任一条件的内容不会被发布:
draft为truedate位于将来publishDate位于将来expiryDate已经过去
为什么这条容易踩:你只挡住了父页面,它下面挂着的子页面照样会出现在站点里,而且不报任何错。子页面成批出现「不该出现的内容」时,先回头检查父页面的状态与 cascade。
运行 hugo build 或 hugo server 时,可以用命令行参数覆盖默认行为:
hugo build --buildDrafts # 或 -D
hugo build --buildExpired # 或 -E
hugo build --buildFuture # 或 -F虽然也可以把这些值写进项目配置,但除非所有内容作者都清楚这些设置,否则可能带来意料之外的结果。
验证标准(用一篇草稿亲手试一次,比读十遍规则有用):
- 新建
content/posts/draft-demo.md,前置元数据里写draft = true; - 执行
hugo build,public/posts/draft-demo/index.html不存在; - 执行
hugo build -D,同一个文件存在。
两条都对,说明草稿规则与 -D 都按预期工作。-D 是 --buildDrafts 的简写,-E、-F 同理。
开发与测试站点
在开发模板或撰写内容时预览站点,切换到项目目录后执行:
hugo serverhugo server 会构建站点,并用一个精简的 HTTP 服务器提供页面。运行时会显示本地站点地址:
Web Server is available at http://localhost:1313/服务器运行期间会监视项目目录中资源(assets)、配置(configuration)、内容(content)、数据(data)、模板(layouts)、翻译(translations)与静态文件(static files)的变化,一旦检测到改动就重建站点,并通过实时重载(LiveReload)刷新浏览器。
多数 Hugo 构建都非常快,除非你正盯着浏览器,否则可能感觉不到这次变化。
你应当看到什么:
- 终端里打印
Web Server is available at …,把浏览器打开到这个地址能看到首页; - 回到编辑器改一个字并保存,浏览器不手动刷新也会自己变;
- 在终端按
Ctrl + C可以停止服务器(终端会回到命令提示符)。
三个常见疑问:
- 改了文件却没反应:监视范围只包括项目目录下的上述几个目录。文件放在项目外面(例如另一个文件夹里的草稿),改了不会触发重建;改的是
public/里的产物也不会——那是输出,不是源码。 - 端口 1313 被占用:用
hugo server --port 1414(或-p 1414)换一个端口。注意以终端实际打印的地址为准,别照抄教程里的 1313。 - 手机或另一台电脑打不开:默认只监听
127.0.0.1(本机回环地址),局域网内其他设备访问不到;确实需要时用hugo server --bind 0.0.0.0,并配合--baseURL让页面里生成的链接指向可访问的地址。
实时重载(LiveReload)
服务器运行时,Hugo 会向生成的 HTML 页面注入 JavaScript。LiveReload 脚本通过 WebSocket 在浏览器与服务器之间建立连接,你不需要安装任何软件或浏览器插件,也不需要做任何配置。
如果浏览器没有自动刷新,先检查它有没有禁用 JavaScript、或者有没有插件拦截了本地页面的脚本。
自动跳转
编辑内容时,如果希望浏览器自动跳转到你最后修改的页面,可以运行:
hugo server --navigateToChanged部署站点
先分清两个词:**发布(publish)**是把源码渲染成 public/ 里的静态文件,**部署(deploy)**是把这些文件送到服务器或托管平台。本节讲发布,部署见托管与部署。
准备好部署时执行:
hugo不带子命令的 hugo 与 hugo build 都是构建命令;本页统一写 hugo build,方便和后面的参数一起读。
这条命令会构建站点,把文件发布到 public 目录,目录结构大致如下:
public/
├── categories/
│ ├── index.html
│ └── index.xml <-- 该 section 的 RSS 订阅
├── posts/
│ ├── my-first-post/
│ │ └── index.html
│ ├── index.html
│ └── index.xml <-- 该 section 的 RSS 订阅
├── tags/
│ ├── index.html
│ └── index.xml <-- 该 section 的 RSS 订阅
├── index.html
├── index.xml <-- 站点级 RSS 订阅
└── sitemap.xml发布完成的验证标准:
public/index.html存在;public/sitemap.xml存在;- 再跑一次
hugo build --cleanDestinationDir,你手动塞进public/的测试文件会被清掉(统计表里Cleaned一行的计数大于 0)。
在简单的托管环境中,通常用 ftp、rsync 或 scp 把文件上传到虚拟主机的根目录,此时 public 目录中的内容就是全部所需文件。
多数用户会把站点部署到 CI/CD(持续集成与持续交付)平台:向远程 Git 仓库推送后触发构建与部署。Git 仓库通常包含整个项目目录,但会排除 public 目录,因为站点是在推送_之后_才构建的。
上传之后最常见的两种情况:
- 页面能打开,但没有样式:最常见的原因是
baseURL还是默认值(https://example.org/之类),于是主题引用的 CSS/JS 变成了指向错误域名的绝对地址。把baseURL改成正式地址后重新构建,见配置 Hugo。 - 删掉的文章线上还能访问:构建不会删除
public/里的旧文件。用--cleanDestinationDir,或者先手动清空再上传。
常见坑速查
按「现象」查,比按命令查快:
| 现象 | 属于哪一类 | 先做什么 |
|---|---|---|
hugo: command not found / 不是内部或外部命令 |
命令找不到 | PATH 没配好 → 安装 Hugo |
命令退出码是 0,但 Pages 数接近 0,或终端只有 WARN found no layout file |
没报错但结果不对 | 多半不在项目根目录(hugo.toml 所在层);用 hugo list all 看内容清单是否只有表头 |
| 草稿文章在浏览器里看不到 | 没报错但结果不对 | 用 hugo server -D,或把 draft 改成 false |
| 删掉的文章上线后还能访问 | 没报错但结果不对 | public/ 里有旧文件 → --cleanDestinationDir |
| 页面都能打开,但完全没有样式 | 没报错但结果不对 | baseURL 没改成正式地址 → 配置 Hugo |
报错里出现 toml: invalid character at start of key: U+00FF |
报错看不懂 | 配置文件被写成了 UTF-16 编码 → 见快速开始的「Windows 用户的坑」 |
| 报错提到某个短代码或模板找不到,但你觉得自己没写 | 报错看不懂 | 见故障排查中关于短代码与模板查找的条目 |
更系统的排查手段(日志、性能、站点审计)在故障排查。