环境准备

# 安装 Hugo（Ubuntu/Debian）
sudo apt install hugo

# 验证安装
hugo version
# 输出示例：hugo v0.154.5+extended linux/amd64

# 查看帮助
hugo help
hugo new --help    # 子命令帮助

站点管理

创建新站点

hugo new site myblog
cd myblog

生成目录结构：

myblog/
├── archetypes/   # 文章模板（frontmatter 预设）
├── assets/       # 待处理的资源文件
├── content/      # 文章内容（Markdown）
├── data/         # 数据文件（YAML/JSON/TOML）
├── layouts/      # 自定义模板
├── static/       # 静态文件（图片、CSS、JS）
├── themes/       # 主题
├── hugo.toml     # 站点配置文件
└── public/       # 构建输出目录（生成后自动创建）

配置站点

编辑 hugo.toml：

baseURL = "https://example.com"
languageCode = "zh-cn"
title = "My Blog"
theme = "papermod"

[params]
  description = "A personal blog"

[menu]
  [[menu.main]]
    identifier = "posts"
    name = "文章"
    url = "/posts/"
    weight = 1

文章管理

创建新文章

# 创建单篇 Markdown 文件
hugo new posts/my-first-post.md

# 创建页面包（Page Bundle，推荐）
hugo new posts/my-first-post/index.md

创建后自动生成 frontmatter（基于 archetypes/default.md）：

---
title: "My First Post"
date: 2026-06-15T00:00:00+08:00
draft: true
---

draft: true 表示草稿，构建时默认不会发布。

自定义 Archetype（文章模板）

编辑 archetypes/default.md：

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
lastmod: {{ .Date }}
draft: true
description: ""
tags: []
categories: []
---

创建指定 archetype 的文章：

hugo new --kind post-bundle posts/with-images/index.md

这会在 archetypes/post-bundle/ 目录下查找模板。

本地预览

启动开发服务器

# 基本模式
hugo server

# 常用参数组合
hugo server \
  --buildDrafts \        # 包含草稿文章
  --disableFastRender \  # 每次修改完整重新渲染（排查布局问题时用）
  --bind 0.0.0.0 \       # 监听所有网卡（局域网其他设备可访问）
  --port 1313 \          # 指定端口（默认 1313）
  --navigateToChanged    # 文件修改后自动跳转到对应页面

启动后访问 http://localhost:1313。

Hugo 开发服务器的核心优势：

特性 说明
热重载 修改 Markdown/模板/配置后，浏览器自动刷新
极速编译 毫秒级，即使上千篇文章也几乎瞬间完成
草稿可见 --buildDrafts 让草稿在本地可见，但不会发布到生产

构建与发布

生产构建

# 标准构建
hugo

# 构建到指定目录
hugo --destination /var/www/myblog

# 清理缓存后构建
hugo --ignoreCache

# 构建时包含草稿（通常不用于生产）
hugo --buildDrafts

构建完成后，所有静态文件输出到 public/ 目录，可以直接部署到任何 Web 服务器。

环境变量

# 指定环境（可在模板中用 .Site.Params.env 判断）
hugo --environment production

# 指定配置文件
hugo --config config.production.toml

主题管理

安装主题

# 方式一：Git submodule（推荐，方便更新）
git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/papermod

# 方式二：直接 clone
git clone https://github.com/adityatelange/hugo-PaperMod.git themes/papermod

# 方式三：下载到 themes/ 目录

在 hugo.toml 中启用：

theme = "papermod"

查看可用主题

ls themes/

主题覆盖

Hugo 的模板查找顺序：layouts/ → themes/<theme>/layouts/。

要覆盖主题的某个模板，在 layouts/ 下创建同名文件即可：

# 覆盖主题的首页模板
cp themes/papermod/layouts/index.html layouts/index.html
# 然后编辑 layouts/index.html

常用命令速查表

命令 用途
hugo new site <name> 创建新站点
hugo new posts/xxx.md 创建新文章
hugo server 启动开发服务器（热重载）
hugo server --buildDrafts 启动开发服务器（含草稿）
hugo 构建生产版本到 public/
hugo --minify 构建并压缩 HTML/CSS/JS
hugo list drafts 列出所有草稿
hugo list future 列出所有未来发布的文章
hugo config 查看当前生效的配置
hugo env 查看 Hugo 版本和环境信息
hugo version 查看 Hugo 版本
hugo mod get -u 更新 Hugo Modules
hugo mod tidy 清理未使用的模块

实际工作流示例

日常写作流程

# 1. 创建新文章
hugo new posts/my-new-article/index.md

# 2. 编辑文章（另一个终端）
vim content/posts/my-new-article/index.md

# 3. 启动预览
hugo server --buildDrafts --navigateToChanged

# 4. 满意后去掉 draft: true

# 5. 构建并部署
hugo
rsync -avz public/ user@server:/var/www/blog/

# 6. 提交到 Git
git add -A
git commit -m "new article: my new article"
git push

批量操作

# 列出所有草稿
hugo list drafts

# 统计文章数量
find content -name "index.md" | wc -l

# 查找包含特定标签的文章
grep -rl "tags:.*Kubernetes" content/

常见问题

Q: hugo server 启动后局域网其他设备无法访问？

hugo server --bind 0.0.0.0

默认只绑定 127.0.0.1，加上 --bind 0.0.0.0 后局域网内其他设备可通过 http://<你的IP>:1313 访问。

Q: 文章创建了但页面上看不到？

检查以下原因：

  1. draft: true — 构建时加 --buildDrafts 或改为 false
  2. date 是未来时间 — Hugo 默认跳过未来文章
  3. 文件不在 content/posts/ 下 — 检查目录结构
  4. 没有 index.md — Page Bundle 模式下需要 index.md

Q: 如何只构建部分内容？

# 只构建某个章节
hugo --contentDir content/posts

# 用标签过滤（需自定义）

Professional English Terms

Term Meaning
Page Bundle 页面包，将文章内容和资源（图片等）放在一个目录中管理
Archetype 文章模板，hugo new 时自动生成 frontmatter 的模板文件
Hot Reload / Live Reload 热重载，修改文件后浏览器自动刷新
Frontmatter 文章开头的元数据（YAML/TOML/JSON），定义标题、日期、标签等
Static Site Generator (SSG) 静态站点生成器，将 Markdown 编译为 HTML 文件