Hugo CLI 命令整理备忘

Hugo 是一个功能强大的静态网站生成器，其核心驱动力来自于其灵活的命令行界面（CLI）。本文旨在整理介绍 Hugo 的常用命令、标志（flags）及其用法。备忘。

核心概念

  • 命令 (Command) ：要执行的主要操作，例如 hugo server 或 hugo new 。
  • 标志 (Flag) ：用于修改命令行为的选项，通常以 - 或 -- 开头，例如 -D 或 --buildDrafts 。

通用语法结构为：

1
hugo [command] [args] [flags]

站点管理

hugo new site

创建一个新的 Hugo 站点骨架。

  • 语法: hugo new site <path>
  • 说明: 在指定的路径下创建一个新的 Hugo 站点目录结构，包含 archetypes, content, data, layouts, static, themes 等文件夹和一个 hugo.toml 配置文件。
  • 示例:
1
2
# 在当前目录下创建一个名为 my-awesome-site 的新站点
hugo new site my-awesome-site

hugo server

启动一个内置的、支持实时重新加载（LiveReload）的 Web 服务器。这是本地开发的核心命令。

  • 语法: hugo server [flags]
  • 说明: 默认情况下，它会在内存中构建站点，并通过 http://localhost:1313/ 提供服务。任何源文件的更改都会立即触发浏览器自动刷新。
  • 常用标志:
  • -D, --buildDrafts: 同时渲染标记为 draft: true 的草稿内容。
  • -E, --buildExpired: 同时渲染已过期的内容。
  • -F, --buildFuture: 同时渲染发布日期在未来的内容。
  • --disableFastRender: 禁用快速渲染模式，在修改模板或配置文件时完全重新构建站点。
  • -p <port>, --port <port>: 指定服务器使用的端口，默认为 1313 。
  • --bind <ip>: 指定服务器绑定的 IP 地址，默认为 127.0.0.1 。设为 0.0.0.0 可允许局域网内其他设备访问。
  • 示例:
1
2
# 启动服务器，并包含草稿内容，允许局域网访问
hugo server -D --bind 0.0.0.0

内容创建

hugo new

根据原型（archetype）创建一个新的内容文件。

  • 语法: hugo new <path/to/content.md>
  • 说明: 这是创建新文章、页面或其他内容的标准方式。它会自动使用 archetypes 目录下的模板来填充新文件的元数据（front matter）。
  • 示例:
1
2
3
4
5
6
7
8
9
10
# 在 content/posts/ 目录下创建一个名为 my-first-post.md 的新文章
hugo new posts/my-first-post.md

# 如果原型文件存在，它会自动填充标题和日期等信息
# 文件内容可能如下：
# ---
# title: "My First Post"
# date: 2025-10-27T10:00:00+08:00
# draft: true
# ---

构建与部署

hugo

构建你的站点。

  • 语法: hugo [flags]
  • 说明: 这是最基础的构建命令。它会读取所有源文件，并将完整的、可部署的静态站点输出到 public 目录（或由配置文件中的 publishDir 指定的目录）。
  • 常用标志:
  • -D, --buildDrafts: 在最终构建中包含草稿。
  • --minify: 压缩最终输出的 HTML, CSS, JS 等文件以减小体积。
  • -b <url>, --baseURL <url>: 覆盖配置文件中的 baseURL ，在部署到不同环境时非常有用。
  • -d <path>, --destination <path>: 指定站点输出目录，覆盖默认的 public 。
  • --cleanDestinationDir: 在构建之前，清空目标目录中与本次构建无关的文件。
  • 示例:
1
2
# 为生产环境构建站点，压缩资源，并指定域名
hugo --minify --baseURL "https://www.example.com/"

主题与模块

hugo mod

管理 Hugo 模块（Go Modules）。这是现代 Hugo 中管理主题和依赖项的推荐方式。

  • hugo mod init: 初始化一个新的模块。
1
2
# 为你的站点初始化一个 Go 模块，通常是你的代码仓库路径
hugo mod init github.com/user/my-site
  • hugo mod get: 下载或更新依赖项。
1
2
3
4
5
# 下载配置文件中定义的所有模块
hugo mod get

# 更新指定的模块
hugo mod get -u github.com/adityatelange/hugo-PaperMod
  • hugo mod clean: 清理模块缓存。
1
hugo mod clean

hugo new theme

创建一个新的主题骨架（传统方式）。

  • 语法: hugo new theme <themename>
  • 示例:
1
hugo new theme my-custom-theme

调试与辅助

hugo version

显示当前安装的 Hugo 版本信息。

1
2
hugo version
# 输出: hugo v0.125.5-b613c2b3f21b5833222435849823d47e1254b818+extended linux/amd64 BuildDate=2024-04-26T16:20:27Z VendorInfo=gohugoio

hugo config

打印站点的最终配置信息（合并了配置文件、主题配置和默认设置）。

1
2
3
4
5
# 打印 TOML 格式的配置
hugo config

# 打印 YAML 格式的配置
hugo config --format yaml

hugo env

打印 Hugo 的环境信息，包括 Go 版本、操作系统等，有助于报告问题。

1
hugo env

hugo list

列出特定类型的内容。

  • hugo list drafts: 列出所有草稿页面。
  • hugo list future: 列出所有发布日期在未来的页面。
  • hugo list expired: 列出所有已过期的页面。

常用全局标志

这些标志可以与大多数命令一起使用。

  • -s, --source <path>: 指定站点源文件目录（默认为当前目录）。
  • -c, --contentDir <path>: 指定内容目录（默认为 content ）。
  • -t, --theme <name>: 指定要使用的主题。
  • --config <path>: 指定一个或多个配置文件（逗号分隔）。
  • -v, --verbose: 输出详细的日志信息。
  • --verboseLog: 更详细的日志，用于深度调试。

综合工作流示例

本地开发流程

  1. 启动开发服务器 ：
1
2
# 实时预览，并包含草稿内容
hugo server -D
  1. 创建新文章 ：
1
hugo new posts/a-new-journey.md
  1. 编辑内容 ：使用你喜欢的编辑器打开 content/posts/a-new-journey.md 并写作。保存后，浏览器会自动刷新。

部署到生产环境

  1. 构建站点 ：
1
2
3
# 假设你的域名是 https://myblog.com
# --cleanDestinationDir 确保没有旧文件残留
hugo --cleanDestinationDir --minify --baseURL "https://myblog.com/"
  1. 部署 ：将 public/ 目录下的所有文件上传到你的 Web 服务器或静态托管服务（如 Netlify, Vercel, GitHub Pages 等）。