Hugo 命令使用指南
Hugo 是基于 Go 语言开发的静态站点生成器，所有核心能力都可以通过命令行完成调用。本指南按使用场景分类，覆盖从项目初始化、本地开发、内容管理到生产构建的全流程命令，并附带参数说明、使用示例和最佳实践。
一、基础命令：帮助与版本查询
1. hugo help
查看 Hugo 所有命令的总览，也可以在任意子命令后加 --help 查看该命令的详细参数。
# 查看所有命令总览
hugo help
# 查看 server 子命令的详细参数
hugo server --help
# 简写
hugo server -h
2. hugo version
查看当前安装的 Hugo 版本、操作系统架构、Go 版本信息，常用于排查兼容性问题。
hugo version
# 输出示例：hugo v0.128.0+extended linux/amd64 BuildDate=...
注意：带
extended标识为扩展版，支持 Sass/SCSS 编译；多数主题需要扩展版才能正常构建。
3. hugo env
打印完整的 Hugo 运行环境信息，包括版本、配置路径、环境变量、模块缓存路径等，排查构建问题时常用。
hugo env
二、项目初始化与主题管理
1. hugo new site
创建一个全新的 Hugo 站点项目，生成标准的目录结构。
语法
hugo new site [项目路径] [flags]
常用参数
| 参数 | 说明 |
|---|---|
--force | 强制在非空目录中创建站点，默认非空目录会报错 |
-f, --format string | 指定配置文件格式，可选 toml（默认）、yaml、json |
--no-config | 不生成默认配置文件 |
示例
# 创建一个名为 my-blog 的站点，配置文件使用 yaml 格式
hugo new site my-blog --format yaml
# 在当前目录强制初始化站点
hugo new site . --force
生成的标准目录结构
my-blog/
├── archetypes/ # 内容原型模板，新建文章时自动套用 Front Matter
├── assets/ # 静态资源（SCSS、JS等），需 Hugo 编译处理
├── content/ # 站点内容（文章、页面等）
├── data/ # 数据文件，可在模板中调用
├── layouts/ # 自定义模板文件
├── public/ # 构建输出目录，自动生成
├── static/ # 纯静态资源，直接复制到输出目录
├── themes/ # 主题目录
└── hugo.toml # 站点主配置文件
2. hugo new theme
快速生成一个自定义主题的基础骨架，包含标准的主题目录结构和模板文件。
语法
hugo new theme [主题名] [flags]
示例
# 在 themes 目录下生成名为 my-theme 的主题骨架
hugo new theme my-theme
3. Hugo Modules 模块管理命令
Hugo Modules 是官方推荐的主题/依赖管理方式，基于 Go Modules 实现，替代传统的 Git 子模块方案。
① hugo mod init
初始化当前项目为 Hugo 模块，生成 go.mod 文件，是使用模块功能的前提。
# 格式：hugo mod init [模块标识，一般用仓库地址]
hugo mod init github.com/yourname/my-blog
② hugo mod get
下载/更新模块（主题、组件等）。
# 安装指定主题模块
hugo mod get github.com/adityatelange/hugo-PaperMod
# 更新所有模块到最新版本
hugo mod get -u
# 更新指定模块到指定版本
hugo mod get github.com/adityatelange/hugo-PaperMod@v7.0
③ hugo mod tidy
清理 go.mod 和 go.sum 中未使用的依赖，保持模块文件整洁。
hugo mod tidy
④ hugo mod vendor
将所有依赖模块下载到本地 vendor 目录，实现离线构建，避免构建时拉取远程依赖。
hugo mod vendor
# 构建时使用本地 vendor 目录
hugo --vendor
三、内容创作与管理
1. hugo new
创建新的内容文件，自动套用对应类型的原型模板（archetypes），生成标准 Front Matter。
语法
hugo new [内容路径] [flags]
常用参数
| 参数 | 说明 |
|---|---|
-k, --kind string | 指定内容类型，对应 archetypes 下的模板名，默认 default |
-d, --date string | 指定文章发布时间，格式如 2024-06-15 |
--draft | 标记为草稿（默认新建的文章就是草稿状态） |
-f, --format string | Front Matter 格式，默认跟随站点配置 |
示例
# 新建一篇文章，路径为 content/posts/hello-world.md
hugo new posts/hello-world.md
# 新建一个独立页面
hugo new about.md --kind page
# 指定发布时间创建文章
hugo new posts/my-post.md --date 2024-07-01
说明：新建的文章默认
draft: true（草稿状态），默认构建和本地服务都不会显示草稿，需加对应参数才能预览。
2. hugo list
列出站点中的内容，常用于快速查看草稿、未来发布文章、所有文章清单。
语法
hugo list [子命令] [flags]
常用子命令
| 子命令 | 说明 |
|---|---|
all | 列出所有内容（包括草稿、已发布、过期） |
drafts | 仅列出所有草稿文章 |
future | 仅列出发布时间在未来的文章 |
expired | 仅列出已过期的文章 |
常用参数
| 参数 | 说明 |
|---|---|
--format string | 输出格式，可选 table（默认）、json、csv |
示例
# 查看所有草稿
hugo list drafts
# 以 JSON 格式导出所有文章清单
hugo list all --format json > posts.json
3. hugo convert
批量转换内容的 Front Matter 格式，支持 TOML、YAML、JSON 互转。
语法
hugo convert [子命令] [flags]
常用子命令
| 子命令 | 说明 |
|---|---|
toTOML | 转换为 TOML 格式 |
toYAML | 转换为 YAML 格式 |
toJSON | 转换为 JSON 格式 |
常用参数
| 参数 | 说明 |
|---|---|
--unsafe | 直接覆盖原文件，默认只输出转换结果不修改源文件 |
示例
# 预览所有文章转换为 YAML 的结果
hugo convert toYAML
# 批量将所有文章的 Front Matter 转换为 YAML 并覆盖原文件
hugo convert toYAML --unsafe
⚠️ 注意：执行
--unsafe前请务必备份内容文件，避免转换出错丢失数据。
四、本地开发服务：hugo server
最常用的核心命令，启动一个本地开发服务器，支持热更新（修改文件后页面自动刷新），默认地址为 http://localhost:1313。
语法
hugo server [flags]
核心常用参数
1. 内容可见性控制
| 参数简写 | 参数全称 | 说明 |
|---|---|---|
-D | --buildDrafts | 构建并显示草稿文章 |
-F | --buildFuture | 构建并显示发布时间在未来的文章 |
-E | --buildExpired | 构建并显示已过期的文章 |
日常开发推荐组合：
hugo server -D，可以预览所有草稿内容。
2. 服务器配置
| 参数 | 说明 |
|---|---|
-p, --port int | 指定服务端口，默认 1313 |
--bind string | 绑定监听地址，设为 0.0.0.0 可让局域网内其他设备访问 |
--baseURL string | 自定义站点根 URL，用于子路径部署预览 |
--noHTTPCache | 禁用浏览器缓存，每次请求都从服务器获取最新内容 |
--disableLiveReload | 关闭热更新自动刷新功能 |
3. 构建与性能
| 参数 | 说明 |
|---|---|
--disableFastRender | 关闭快速渲染，每次修改全量重建，适合排查渲染异常 |
--renderToDisk | 将渲染结果写入 public 目录，默认只存在内存中 |
--gc | 启动时运行垃圾回收，清理无用缓存 |
--minify | 压缩输出的 HTML/CSS/JS，预览生产环境效果 |
-e, --environment string | 指定运行环境，默认 development |
高频使用示例
# 基础开发模式，显示草稿
hugo server -D
# 指定端口为 3000，显示草稿和未来文章
hugo server -D -F --port 3000
# 局域网可访问的开发服务
hugo server -D --bind 0.0.0.0
# 预览生产环境构建效果（压缩、无草稿）
hugo server --minify --environment production
# 关闭缓存，确保每次都获取最新内容
hugo server -D --noHTTPCache
五、生产构建与部署
1. hugo（hugo build）
核心构建命令，将所有内容、模板、资源编译为静态 HTML 文件，输出到 public 目录。
语法
hugo [flags]
核心常用参数
1. 内容控制
和 server 命令一致：-D 包含草稿、-F 包含未来文章、-E 包含过期文章。
生产构建不建议加这三个参数，默认只构建已发布、未过期的文章。
2. 输出与优化
| 参数 | 说明 |
|---|---|
--minify | 压缩所有输出文件（HTML、CSS、JS、XML、JSON），减小体积 |
--gc | 构建完成后运行垃圾回收，清理无用的缓存文件 |
--cleanDestinationDir | 构建前清空 public 目录，避免旧文件残留 |
-d, --destination string | 指定输出目录，默认 public |
--baseURL string | 强制指定站点根 URL，优先级高于配置文件 |
--ignoreCache | 忽略本地缓存，全量重新构建 |
--noTimes | 不保留文件修改时间戳，适合需要可复现构建的场景 |
3. 环境与配置
| 参数 | 说明 |
|---|---|
-e, --environment string | 指定构建环境，默认 production |
--config string | 指定配置文件路径，默认使用根目录的 hugo.toml |
--vendor | 使用本地 vendor 目录的模块进行构建 |
标准生产构建命令（推荐）
# 最常用的生产构建组合：清理旧文件、压缩、垃圾回收
hugo --minify --gc --cleanDestinationDir
# 指定子路径部署
hugo --minify --baseURL https://example.com/blog/
# 指定生产环境构建
hugo --minify -e production
2. hugo deploy
一键将构建好的静态站点部署到云存储服务，支持 AWS S3、Google Cloud Storage、Azure Blob Storage，无需额外部署工具。
使用前提
在配置文件中配置好部署目标和认证信息，执行命令即可自动对比文件差异、上传新文件、删除旧文件。
常用参数
| 参数 | 说明 |
|---|---|
--confirm | 部署前要求手动确认，避免误操作 |
--dryRun | 试运行，只显示要执行的操作不实际上传 |
--force | 强制上传所有文件，跳过差异对比 |
示例
# 试运行部署，查看会执行哪些操作
hugo deploy --dryRun
# 确认后正式部署
hugo deploy --confirm
六、配置与调试命令
1. hugo config
打印当前站点的完整配置信息，包含所有默认值和自定义配置，常用于排查配置不生效的问题。
# 打印所有配置
hugo config
# 筛选查看特定配置（Linux/macOS）
hugo config | grep baseURL
# 查看模块挂载配置
hugo config mounts
# 查看模块相关配置
hugo config modules
2. 调试类参数
所有构建和 server 命令都可以加以下调试参数，定位问题：
| 参数 | 说明 |
|---|---|
--verbose / -v | 输出详细的构建日志 |
--debug | 输出调试级别的日志信息 |
--log | 将构建日志写入文件 |
--printI18nWarnings | 打印国际化翻译缺失的警告 |
--printPathWarnings | 打印路径相关的警告 |
--templateMetrics | 输出模板渲染性能指标，优化构建速度用 |
--ignoreErrors | 忽略指定类型的错误，继续构建 |
3. hugo benchmark
对站点构建进行性能基准测试，输出构建各阶段的耗时，用于定位构建慢的原因。
# 运行 5 次构建，统计平均性能
hugo benchmark -n 5
七、高级工具命令
1. hugo gen 生成系列命令
① hugo gen chromastyles
生成代码高亮的 CSS 样式文件，Hugo 使用 Chroma 进行代码高亮，支持多种主题。
# 生成 monokai 主题的高亮样式，输出到 assets/css/syntax.css
hugo gen chromastyles --style monokai > assets/css/syntax.css
所有可用主题：Chroma 官方主题库
② hugo gen doc
生成 Hugo 所有命令的 Markdown 格式文档。
hugo gen doc --dir ./hugo-docs
③ hugo gen man
生成 Unix man 手册页格式的命令文档。
2. hugo version
查看版本信息，前文已提及，补充：加 --verbose 可查看更详细的构建信息。
八、高频实用命令组合速查
| 场景 | 命令 |
|---|---|
| 初始化新站点（YAML配置） | hugo new site my-blog -f yaml |
| 日常本地开发 | hugo server -D |
| 局域网预览开发 | hugo server -D --bind 0.0.0.0 -p 3000 |
| 查看所有草稿 | hugo list drafts |
| 标准生产构建 | hugo --minify --gc --cleanDestinationDir |
| 子路径部署构建 | hugo --minify --baseURL https://yoursite.com/blog/ |
| 排查构建问题 | hugo --verbose --debug |
| 清理模块依赖 | hugo mod tidy |
| 离线构建准备 | hugo mod vendor |
九、常见注意事项
- 扩展版依赖：如果主题使用了 SCSS/Sass、PostCSS 等特性，必须安装 Hugo Extended 版本，否则构建会报错。
- 草稿状态：默认生产构建不会包含草稿、未来文章、过期文章，发布前请确认文章
draft为false，发布时间正确。 - 环境区分：通过
--environment可以区分开发/生产环境，在配置文件中可以按环境设置不同参数（比如统计代码、评论系统只在生产环境开启）。 - 缓存问题：构建异常时可尝试删除
resources缓存目录，或加--ignoreCache参数全量重建。 - 命令帮助：任何命令不确定参数时，加
--help即可查看官方完整说明，是最权威的参考。