Hugo 命令行用法完整指南

创建日期：October 27, 2025 修改日期：October 27, 2025

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

1. 核心概念

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

通用语法结构为：

hugo [command] [args] [flags]

2. 站点管理

`hugo new site`

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

语法: hugo new site <path>
说明: 在指定的路径下创建一个新的 Hugo 站点目录结构，包含 archetypes, content, data, layouts, static, themes 等文件夹和一个 hugo.toml 配置文件。

示例:

# 在当前目录下创建一个名为 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 可允许局域网内其他设备访问。

示例:

# 启动服务器，并包含草稿内容，允许局域网访问
hugo server -D --bind 0.0.0.0

3. 内容创建

`hugo new`

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

语法: hugo new <path/to/content.md>
说明: 这是创建新文章、页面或其他内容的标准方式。它会自动使用 archetypes 目录下的模板来填充新文件的元数据（front matter）。

示例:

# 在 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
# ---

4. 构建与部署

`hugo`

构建你的站点。

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

示例:

# 为生产环境构建站点，压缩资源，并指定域名
hugo --minify --baseURL "https://www.example.com/"

5. 主题与模块

`hugo mod`

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

hugo mod init: 初始化一个新的模块。

# 为你的站点初始化一个 Go 模块，通常是你的代码仓库路径
hugo mod init github.com/user/my-site

hugo mod get: 下载或更新依赖项。

# 下载配置文件中定义的所有模块
hugo mod get

# 更新指定的模块
hugo mod get -u github.com/adityatelange/hugo-PaperMod

hugo mod clean: 清理模块缓存。
```
hugo mod clean
```

`hugo new theme`

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

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

6. 调试与辅助

`hugo version`

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

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

`hugo config`

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

# 打印 TOML 格式的配置
hugo config

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

`hugo env`

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

hugo env

`hugo list`

列出特定类型的内容。

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

7. 常用全局标志

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

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

8. 综合工作流示例

本地开发流程

启动开发服务器：

# 实时预览，并包含草稿内容
hugo server -D

创建新文章：
```
hugo new posts/a-new-journey.md
```
编辑内容：使用你喜欢的编辑器打开 content/posts/a-new-journey.md 并写作。保存后，浏览器会自动刷新。

部署到生产环境

构建站点：

# 假设你的域名是 https://myblog.com
# --cleanDestinationDir 确保没有旧文件残留
hugo --cleanDestinationDir --minify --baseURL "https://myblog.com/"

部署：将 public/ 目录下的所有文件上传到你的 Web 服务器或静态托管服务（如 Netlify, Vercel, GitHub Pages 等）。

Hugo 命令行用法完整指南