快速开始
手把手从零跑通第一个 Hugo 站点:装好环境、创建项目、写第一篇内容、在浏览器里看到它,最后发布成静态文件。每一步都给验证方法。
开始之前,你需要
- 一台电脑,以及管理员的耐心——第一次安装需要改动系统设置(Windows 需要配置环境变量,macOS 需要确认安全提示)。
- 会打开终端并输入命令。若从没接触过命令行,请先读下面「第 0 步」,那里把每一类命令都解释了一遍。
- 能连外网。本教程要克隆一个主题仓库;离线环境请改读 安装 Hugo 的选择。
读完之后你能
- 在自己的操作系统上确认 Hugo 可用、版本不低于 v0.158.0;
- 用
hugo new project生成一个完整项目骨架,并启动开发服务器在浏览器里看到页面; - 写出一篇带前置元数据(front matter)的文章,并理解
draft为什么会让它不显示; - 把站点渲染成
public/目录下的静态文件,知道接下来该去读哪几页。
这一页的目标只有一个:让你在半小时内,在自己电脑上真正跑起来一个 Hugo 站点,而不是读完一堆概念。走完之后你会有一个能看的本地站点、一篇自己写的文章,以及一个可以上传到任何静态托管平台的 public/ 目录。
本页只走主线。想要「为什么」的读者,每完成一步后面都给了对应章节的入口;想先了解 Hugo 是什么,可以看简介。
第 0 步:先把环境这件事说清楚
这一步不算在「四件事」里,但它决定了后面会不会卡住。跳过这一步,是新手最常见的第一处卡点。
先确认终端能跑起来
后面的命令都要在终端里执行。按你的系统打开它:
| 系统 | 打开方式 | 说明 |
|---|---|---|
| Windows | 开始菜单搜索 PowerShell,打开名为「PowerShell 7」或「PowerShell」的那个应用 | 见下方「Windows 用户的坑」 |
| macOS | Command + 空格,输入 Terminal 回车 |
系统自带,无需安装 |
| Linux | Ctrl + Alt + T,或在应用列表里找「终端」 |
各发行版略有差异 |
Windows 用户的坑:别用「Windows PowerShell」
Windows 上叫「PowerShell」的应用其实有两个,它们不是同一个软件:
- PowerShell 7(应用名
PowerShell,命令是pwsh):本教程命令可以直接用; - Windows PowerShell 5.1(应用名
Windows PowerShell,命令是powershell):不要用它执行本教程的命令。
原因不是风格问题,而是它会把配置文件写坏。本教程里有一句给项目配置追加主题的命令:
echo "theme = 'ananke'" >> hugo.toml在 Windows PowerShell 5.1 里,>> 重定向默认写 UTF-16LE 编码并带 BOM。写入后 Hugo 读这个文件会直接报错:
ERROR failed to load config: "…/hugo.toml:1:1": unmarshal failed:
toml: invalid character at start of key: U+00FF 'ÿ'这句报错会让人以为是 Hugo 坏了或者语法写错了,其实是编码问题——文件开头多了两个字节 FF FE,TOML 解析器不认。
要确认自己用的是哪个,在终端里看提示符前面有没有 PS 无所谓,直接查版本:
$PSVersionTable.PSVersion- 输出
Major为 7 或更高 → 可以直接用本教程命令; - 输出
Major为 5.1 → 换用 PowerShell 7,或者用 WSL / Git Bash 等 Linux 终端。
不想装 PowerShell 7 也行:把那句
echo … >>换成用编辑器手动打开hugo.toml,在文件末尾加一行theme = 'ananke',效果完全相同。这是本教程里唯一需要 shell 重定向的地方。
确认 Hugo 已安装
先安装 Hugo(任何发行版都可以,但版本不能低于 v0.158.0):
- Windows / macOS / Linux 各平台的安装方式,见安装 Hugo;
- 只想最省事:macOS 用
brew install hugo,Windows 用winget install Hugo.Hugo.Extended,Linux 用发行版包管理器或去发布页下载对应压缩包。
然后在这里验证。这是第一个检查点:
hugo version你应当看到类似输出(版本号 ≥ v0.158.0 即可):
hugo v0.167.0+extended windows/amd64 ...看到 command not found 或「不是内部或外部命令」,说明 Hugo 没装好,或者装了但没进 PATH:回到安装 Hugo 按平台步骤重做,不要带着这个问题往下走。
确认 Git 已安装
本教程用 Git 来拉取主题:
git --version同样,报错就先装 Git(git-scm.com)。
第 1 步:创建项目
三条命令,先跑再解释。记得用上面确认过的终端。
hugo new project quickstart
cd quickstart
git init
git submodule add https://github.com/gohugo-ananke/ananke themes/ananke
echo "theme = 'ananke'" >> hugo.toml
hugo server在终端最后一行会打印一个本地网址(通常是 http://localhost:1313/)。用浏览器打开它——你应该看到一个已经成型的站点,有首页、有示例导航。这就是 Hugo 的开发服务器(development server):它监视文件变化并自动刷新页面。
按 Ctrl + C 停止开发服务器。
逐条解释这几条命令
① 生成项目骨架
hugo new project quickstart在 quickstart 目录里创建项目骨架:一份 hugo.toml 配置、content/、layouts/、assets/ 等目录,以及一篇示例首页内容。它不包含主题——这是下一步要做的事。
② 进入项目目录
cd quickstartcd 是 change directory。后面的命令都必须在项目根目录下执行;忘了这一步,Hugo 会找不到 hugo.toml,构建出一个空站点(而且不报错)。
③ 初始化 Git 仓库
git init④ 以 Git 子模块方式加入主题
git submodule add https://github.com/gohugo-ananke/ananke themes/ananke把 Ananke 主题克隆到 themes/ananke,并在 .gitmodules 里登记为子模块。选子模块而不是直接复制,是为了让主题跟着上游更新。这一步需要联网。
嫌子模块麻烦(比如不打算用 Git 管理站点),可以把
git submodule add …换成git clone https://github.com/gohugo-ananke/ananke themes/ananke,效果对构建而言一样。
⑤ 告诉 Hugo 用哪个主题
echo "theme = 'ananke'" >> hugo.toml向 hugo.toml 末尾追加一行主题声明。Windows 用户务必用第 0 步确认过的终端。
⑥ 启动开发服务器
hugo serverHugo 在这里做了一次完整构建,然后起了一个本地 HTTP 服务并开始监视文件。终端会打印站点地址与页面数量;地址就是你要在浏览器里打开的。
这一步的验证标准
- 浏览器打开
http://localhost:1313/能看到站点首页与主题自带的示例文章; - 终端里没有
ERROR字样; - 在浏览器里改一下地址,站点还有别的页面(例如主题自带的
About)。
三者都满足才继续。只有第一条满足但终端有报错,请把报错贴到官方论坛中文分类 或先查故障排查。
第 2 步:添加你的第一篇内容
保持开发服务器运行,另开一个终端窗口(同一个窗口里按 Ctrl + C 会把服务器停掉),进入项目目录:
hugo new content content/posts/my-first-post.mdHugo 会在 content/posts/ 下创建这个文件。用任意编辑器打开它,内容大致是:
+++
title = 'My First Post'
date = 2024-01-14T07:07:07+01:00
draft = true
+++顶部用 +++ 包起来的是前置元数据(front matter):Hugo 用它描述页面,而不是把它渲染成正文。三个字段的含义分别是:
| 字段 | 作用 |
|---|---|
title |
页面标题 |
date |
发布日期 |
draft |
true 表示这是草稿,正式构建时不发布 |
为什么你的文章「不见了」
draft = true 是新手遇到的第二处卡点:写完文章、刷新浏览器,文章不在列表里。这不是出错,而是 Hugo 的默认策略——草稿不发布。
两个选择:
hugo server -D # 连同草稿一起预览(-D 是 --buildDrafts 的简写)
hugo server --buildDrafts # 与上一行完全等价内容定稿后,把 draft 改成 false,它就会出现在正式构建中。草稿、定时发布(publishDate)、过期内容(expiryDate)的完整规则见基本用法。
给文章写点正文
在第二个 +++ 下面接着写 Markdown:
+++
title = 'My First Post'
date = 2024-01-14T07:07:07+01:00
draft = true
+++
## 简介
这是**粗体**文字,这是*强调*文字。
访问 [Hugo](https://gohugo.io) 官网!保存文件后浏览器会自动刷新(开发服务器在监视文件)。这里要注意:正文标题用 ##,不用 #——# 一级标题由页面自身承担,重复写会出现两个 <h1>。
Markdown 的解析遵循 CommonMark 规范;拿不准某种写法会渲染成什么时,可以用官方的在线测试工具先试。
这一步的验证标准
hugo server -D之后,浏览器里能看到My First Post这篇文章;hugo server(不带-D)之后,它不出现——这恰好证明草稿规则生效了。
第 3 步:配置项目
用编辑器打开项目根目录下的项目配置文件 hugo.toml:
baseURL = 'https://example.org/'
locale = 'en-us'
title = 'My New Hugo Project'
theme = 'ananke'改三处:
baseURL—— 将来站点的正式地址。必须是协议开头、斜杠结尾(https://example.org/),否则 RSS、站点地图和站内绝对链接会指向错误位置。locale—— 你的区域,例如简体中文写zh-cn。它影响日期与数字的本地化格式。title—— 站点标题,会出现在浏览器标签与主题页头。
改完重新预览(记得带草稿):
hugo server -D配置键很多,但不要一次改一堆。先让站点跑起来,再按需到配置里逐项查。改了配置不生效时,先确认改的是项目根目录下的
hugo.toml。
第 4 步:发布(生成静态文件)
注意区分两个词:这一步是发布(publish),不是部署(deploy)。发布是把源码渲染成静态文件,部署是把这些文件送到服务器或托管平台上。
hugoHugo 会把全部产物写进项目根目录的 public/:每个页面的 HTML,以及图片、CSS、JavaScript 等资源。public/ 就是可以原样上传的成品。
两个常见疑问:
public/要不要提交进 Git? 不要。它是构建产物,加进.gitignore即可。- 构建时刷新了草稿? 检查是否还有
draft = true的页面。默认hugo不包含草稿。
发布完成后,public/ 里应当有 index.html。本地想验证成品,可以用任意静态服务器打开它,例如:
hugo server --renderToMemory # 或者简单地重新用 hugo server 预览要真正部署到线上,见托管与部署。
卡住了怎么办
按现象查最快的入口:
| 现象 | 先查这里 |
|---|---|
hugo: command not found / 不是内部或外部命令 |
Hugo 没进 PATH → 安装 Hugo 对应平台小节 |
unmarshal failed: toml: invalid character at start of key: U+00FF |
配置被写成了 UTF-16 → 回到本页「Windows 用户的坑」 |
| 页面数突然变成 0 或很少,且没有报错 | 不在项目根目录执行,或 theme 没生效 → 见目录结构与故障排查 |
| 站点没有样式,页面像纯文本 | 主题没装好或 theme 写错 → 检查 themes/ananke 是否存在 |
| 文章不显示 | draft = true → 用 hugo server -D,或把 draft 改成 false |
| 构建报「短代码未闭合」但内容里明明没有短代码 | 看疑难解答中关于短代码占位符的条目 |
提问时请附上 hugo version 的输出、完整报错,以及能复现问题的最小项目结构——这会显著提高被解答的速度。中文用户可以去官方论坛的中文分类,其余分类有两万多个主题可直接搜索。
接下来读什么
到这里主线已经跑完。按你下一步想做的事选: