月 · 半 · 网

Hugo常用命令使用指南

 技术  1798  4 分钟

鉴于本站是Hugo搭建，记录下常用命令，方便我快速查找和使用：

一、基础命令（核心操作）

1. 查看 Hugo 版本

1
2


hugo version
  • 作用：确认当前安装的 Hugo 版本（区分 Hugo 和 Hugo Extended 版本，Extended 支持 Sass/SCSS 编译）。

2. 创建新站点

1
2


hugo new site my-blog

  • 作用：在当前目录下创建一个名为 my-blog 的新 Hugo 站点（生成基础目录结构）。

  • 进入站点目录：cd my-blog。

3. 添加主题

Hugo 站点需要主题才能渲染页面，常用两种方式：

方式 1：直接下载主题（推荐本地开发）
1
2
3
4
5


# 进入 themes 目录
cd themes
# 克隆主题仓库（以主流主题 PaperMod 为例）
git clone https://github.com/adityatelange/hugo-PaperMod.git
方式 2：使用 Hugo Modules（推荐生产环境，无需本地存储主题）
1
2
3
4
5


# 初始化 Hugo Modules（首次使用需执行）
hugo mod init github.com/your-username/my-blog
# 添加主题作为依赖（自动下载到模块缓存）
hugo mod get github.com/adityatelange/hugo-PaperMod
  • 配置主题：修改站点根目录的 hugo.toml，添加 theme = "hugo-PaperMod"（或模块路径 theme = "github.com/adityatelange/hugo-PaperMod"）。

4. 创建新内容（文章 / 页面）

1
2
3
4
5
6
7
8
9


# 创建一篇新文章（默认生成在 content/posts/ 目录下）
hugo new posts/my-first-post.md

# 创建一个新页面（生成在 content/ 目录下，如关于页）
hugo new about.md

# 创建带日期的文章（部分主题支持自动按日期分类）
hugo new posts/2024-05-20-my-post.md
  • 生成的文件是 Markdown 格式，包含 Front Matter（元数据，如标题、日期、标签等），可直接编辑。

5. 本地开发预览

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# 启动本地开发服务器（默认端口 1313）
hugo server

# 启动服务器并自动打开浏览器
hugo server --open

# 允许局域网内其他设备访问（如手机测试）
hugo server --bind 0.0.0.0 --baseURL http://你的IP:1313

# 禁用缓存（强制重新生成所有页面，解决缓存导致的更新不生效问题）
hugo server --disableFastRender
  • 特性：实时热重载（修改内容或配置后，浏览器自动刷新），方便实时预览。

6. 构建静态站点（生成最终文件）

1
2
3
4
5
6
7
8
9


# 构建站点（默认输出到 public/ 目录）
hugo

# 构建时显示详细日志（用于排查错误）
hugo --verbose

# 构建前清理旧的 public/ 目录（避免残留文件）
hugo --clean
  • 生成的 public/ 目录包含所有静态文件（HTML、CSS、JS、图片等），可直接部署到 GitHub Pages、Netlify、Vercel 等平台。

二、进阶命令（优化与部署）

1. 指定输出目录

1
2


hugo --destination ./docs
  • 作用：将构建结果输出到 docs/ 目录（适合 GitHub Pages 要求的 docs/ 目录部署）。

2. 自定义基础 URL

1
2


hugo --baseURL "https://your-domain.com/"
  • 作用：指定站点的基础 URL（生产环境必须配置，否则资源路径可能错误），也可在 hugo.toml 中直接配置 baseURL = "https://your-domain.com/"。

3. 构建草稿 / 未来文章

1
2
3
4
5
6
7
8
9


# 构建草稿文章（文章 Front Matter 中 draft: true 的内容）
hugo --buildDrafts

# 构建未来时间的文章（文章日期在当前时间之后的内容）
hugo --buildFuture

# 构建所有内容（草稿 + 未来文章 + 过期文章）
hugo --buildAll
  • 场景：本地预览草稿时使用 hugo server -D（-D 是 --buildDrafts 的缩写）。

4. 生成站点地图

1
2


hugo --sitemap
  • 作用：自动生成 sitemap.xml（搜索引擎收录用），部分主题已集成，无需额外配置。

5. 使用 Hugo Modules 管理依赖

1
2
3
4
5
6
7
8
9


# 更新所有模块（主题、插件等）
hugo mod get -u

# 更新指定模块（如仅更新主题）
hugo mod get -u github.com/adityatelange/hugo-PaperMod

# 清理模块缓存（解决模块下载失败问题）
hugo mod clean

三、其他常用命令

1. 查看站点信息

1
2


hugo env
  • 作用：显示 Hugo 环境信息（版本、操作系统、Go 版本、模块信息等），用于排查环境相关问题。

2. 验证配置文件

1
2


hugo config
  • 作用：打印当前站点的完整配置（合并 hugo.toml 和命令行参数），检查配置是否正确。

3. 清理 Hugo 缓存

1
2


hugo mod clean
  • 作用：清理模块缓存和临时文件（解决依赖冲突或缓存导致的异常）。

四、常用配置（补充）

虽然不是命令，但 hugo.toml（Hugo 111+ 推荐使用，替代旧的 config.toml）中的核心配置会影响命令执行效果，常用配置如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# 基础信息
baseURL = "https://your-domain.com/"
languageCode = "zh-cn"  # 站点语言（如 en-us）
title = "我的博客"       # 站点标题
theme = "hugo-PaperMod" # 主题名称（或模块路径）

# 作者信息
[author]
  name = "张三"
  email = "zhangsan@example.com"

#  taxonomies（分类、标签）
[taxonomies]
  category = "categories"  # 分类（URL: /categories/）
  tag = "tags"             # 标签（URL: /tags/）

# 构建配置
[build]
  useResourceCacheWhen = "always"  # 启用资源缓存（加速构建）

总结

  • 本地开发：hugo new 创建内容 → hugo server 预览；

  • 生产部署：hugo 构建 → 上传 public/ 目录到服务器；

  • 进阶优化：用 Hugo Modules 管理主题，配置 hugo.toml 自定义站点信息。

如果需要更详细的命令参数，可以通过 hugo help <命令> 查看（如 hugo help server）。

updatedupdated2025-11-242025-11-24

相关文章：