HUGO介绍、安装、以及使用

HUGO官方网站，文章内容的简介大部分来自官网的翻译，官网是纯英文描述，英语好的可以前往官方网站，博主在这里简介中简单翻译处理包括一些链接的引用，主要是讲解一下如何安装和使用。

这里再粘贴一个三方网站opendocs.io的HUGO官方网站英文版的翻译网站

简介（取自HUGO官网）：

一个快速灵活的静态站点生成器，由bep、spf13和Go的friends精心构建。

Hugo 是一个用Go编写的静态网页生成器，可以在几秒钟内（通常更短）呈现完整的网站。

由于其灵活的框架、多语言支持和强大的分类系统，Hugo 被广泛用于创建：

• 企业、政府、非营利组织、教育、新闻、活动和项目网站
• 文档站点
• 图片集
• 登陆页面
• 商业、专业和个人博客
• 简历和履历

在开发过程中使用 Hugo 的嵌入式 Web 服务器可以即时查看内容、结构、行为和演示的更改。然后将网站部署到您的主机，或将更改推送到您的 Git 提供程序以进行自动构建和部署。

Hugo 的快速资产管道包括：

• 图像处理——转换、调整大小、裁剪、旋转、调整颜色、应用过滤器、叠加文本和图像以及提取 EXIF 数据
• JavaScript 捆绑——将 TypeScript 和 JSX 转换为 JavaScript、捆绑、树形摇动、最小化、创建源映射并执行 SRI 散列。
• Sass 处理 - 将 Sass 转换为 CSS、捆绑、树摇、最小化、创建源映射、执行 SRI 哈希以及与 PostCSS 集成
• Tailwind CSS 处理 - 将 Tailwind CSS 实用程序类编译为标准 CSS、捆绑、树摇、优化、最小化、执行 SRI 哈希并与 PostCSS 集成

使用Hugo 模块，您可以通过公共或私有 Git 存储库与其他项目共享内容、资产、数据、翻译、主题、模板和配置。

请参阅文档的功能部分，以获得 Hugo 功能的全面摘要。

一、版本介绍

hugo有三个版本标准版、拓展版、拓展/部署版

推荐安装拓展版本

1、Hugo 标准版

• 适合 一般的 Hugo 站点，如果不需要 SCSS/SASS 处理，可以使用。

• 仅支持纯 HTML/CSS/JS，不能编译 SASS/SCSS，也 不支持 PostCSS。

• 运行速度快，适用于 轻量级博客或文档站点。

• 适用场景：

  • 纯 Markdown 转 HTML
  • 个人博客、技术文档网站
  • 没有复杂的前端需求

• 执行命令：hugo version

  • 显示类似：
    hugo v0.145.0 linux/amd64 BuildDate=unknown
    

2、Hugo 拓展版（Extended）

• 支持 SCSS/SASS 编译（Hugo Pipes）

• 支持 PostCSS 处理

• 适用于 需要前端优化、CSS 预处理、优化静态资源的站点

• 是标准版的超集（包含标准版的所有功能）

• 适用场景：

  • 需要使用 SCSS/SASS 预处理 CSS
  • 需要 Tailwind CSS、Autoprefixer
  • 希望 Hugo 直接优化 CSS/JS 资源

• 执行命令：hugo version

  • 显示类似：
    hugo v0.145.0+extended linux/amd64 BuildDate=unknown
    

3、Hugo 开发版（Dev/HEAD）

• 最新 Hugo 开发中的版本，包含 Hugo 团队最新的功能和改进

• 可能有新特性，但不稳定，不推荐用于生产环境

• 适合 Hugo 主题和插件开发者测试最新功能

• 适用场景：

  • 需要 Hugo 的最新功能

  • 参与 Hugo 社区贡献

  • 主题开发者或高级用户

• 执行命令：hugo version

  • 显示类似：
    hugo v0.145.0+extended,withdeploy linux/amd64 BuildDate=unknown
    

4、比对表

二、安装（Linux、Windows、Mac）

再强调一遍推荐安装拓展版，因为大部分模板都需要Sass等其他处理

1、源代码构建（通用于任何平台）

注意：源代码构建可以忽略GCC这个点，一般情况下源代码构建是一些较低的版本不支持，像hugo0.56.0这种远古版本，新版本都没什么问题。

前置条件，Linux、Windows、Mac中必须安装go编译器，参照如下：

• 标准版：Go 1.23.0 或更高版本
• 扩展版：Go 1.23.0 或更高版本，以及 GCC
• 扩展/部署版本：Go 1.23.0 或更高版本，以及 GCC

构建标准版

go install github.com/gohugoio/hugo@latest

构建扩展版本

CGO_ENABLED=1 go install -tags extended github.com/gohugoio/hugo@latest

构建扩展/部署版本

CGO_ENABLED=1 go install -tags extended,withdeploy github.com/gohugoio/hugo@latest

检查是否安装成功

hugo version
# 显示版本信息即安装成功，类似如下内容：
hugo v0.145.0+extended,withdeploy linux/amd64 BuildDate=unknown

2、二进制文件安装（通用于任何平台）

推荐使用最新版本，下载链接

1.Linux安装（要区分arm和amd）

amd架构：x86_64 (AMD64)适用于基于 Intel 和 AMD 的 64位处理器

arm架构：aarch64适用于 ARM64 架构的处理器（例如树莓派或其他 ARM 设备）

使用命令：uname -m 即可查看架构；如下CentOS/Ubuntu比较常用的，其它也是按照这两种方式

• CentOS

  • Linux下载类似这种名称（extended代表扩展版本）：

    • amd架构：hugo_extended_0.145.0_linux-amd64.tar.gz

    • arm架构：hugo_extended_withdeploy_0.145.0_linux-arm64.tar.gz

  • 下载命令：wget https://github.com/gohugoio/hugo/releases/download/v0.145.0/hugo_extended_0.145.0_linux-amd64.tar.gz

  • 解压：tar -zxvf hugo_extended_0.145.0_linux-amd64.tar.gz

  • 切换路径：cd hugo_extended_0.145.0_linux-amd64

  • 移动到目录/usr/local/bin/下：sudo mv hugo /usr/local/bin/

  • 检查安装，终端输入：hugo version

  • 显示版本信息成功，即安装完成，显示信息类似如下：

    hugo v0.145.0+extended linux/amd64 BuildDate=unknown

• Ubuntu

  • Linux下载类似这种名称（extended代表扩展版本）：

    • amd架构：hugo_extended_withdeploy_0.145.0_linux-amd64.deb
    • arm架构：hugo_extended_withdeploy_0.145.0_linux-arm64.deb

  • 下载命令：wget https://github.com/gohugoio/hugo/releases/download/v0.145.0/hugo_extended_withdeploy_0.145.0_linux-amd64.deb

  • 下载安装dpkg（如果存在可省略此步骤-左侧是Ubuntu命令）

    • sudo apt-get update
    • sudo apt-get install dpkg

  • 安装命令：sudo dpkg -i hugo_extended_withdeploy_0.145.0_linux-amd64.deb

  • 检查安装，终端输入：hugo version

  • 显示版本信息成功，即安装完成，显示信息类似如下：

    hugo v0.145.0+extended linux/amd64 BuildDate=unknown

2.Windows安装

• Windows下载类似这种名称（extended代表扩展版本）：hugo_extended_withdeploy_0.145.0_windows-amd64.zip

• 官网下载，下载后解压压缩包，进入到目录hugo_extended_withdeploy_0.145.0_windows-amd64，复制hugo文件所在的路径例如D:\SoftFile\hugo_extended_0.145.0_Windows-64bit\

• 配置环境变量

  • Win11位置：系统 > 系统信息 > 高级系统设置 > 环境变量(N)... > 系统变量(S)
  • 找到Path变量，添加新的环境变量D:\SoftFile\hugo_extended_0.145.0_Windows-64bit\

• 检查安装，终端输入：hugo versiion

• 显示版本信息成功，即安装完成，显示信息类似如下：

  hugo v0.145.0+extended linux/amd64 BuildDate=unknown

3.Mac安装

• Mac下载类似这种名称（extended代表扩展版本）：hugo_extended_withdeploy_0.145.0_darwin-universal.tar.gz

• 直接下载或者命令下载，下载命令：wget https://github.com/gohugoio/hugo/releases/download/v0.145.0/hugo_extended_withdeploy_0.145.0_darwin-universal.tar.gz 或 curl -LO https://github.com/gohugoio/hugo/releases/download/v0.145.0/hugo_extended_withdeploy_0.145.0_darwin-universal.tar.gz

• 解压：tar -xvzf hugo_extended_withdeploy_0.145.0_darwin-universal.tar.gz

• 切换路径：cd hugo_extended_withdeploy_0.145.0_darwin-universal

• 移动到目录/usr/local/bin/下：sudo mv hugo /usr/local/bin/

• 检查安装，终端输入：hugo version

• 显示版本信息成功，即安装完成，显示信息类似如下：

  hugo v0.145.0+extended linux/amd64 BuildDate=unknown

3、系统命令安装

除了Mac，强烈建议使用上面两种方式安装；至于为什么，因为有坑，而且是大坑，这里就涉及到文章开头提到的GCC，再就是版本问题，下面会讲解到。

例如：centos的yum，Ubuntu的apt-get，Mac常用的Homebrew

1.CentOS

• 安装启用 EPEL 仓库，Hugo 需要从 EPEL（Extra Packages for Enterprise Linux） 仓库安装，因此如果系统没有启用 EPEL，先运行以下命令：sudo yum install epel-release -y

• 更新仓库：sudo yum update -y

• 下载安装（默认标准版）：sudo yum install hugo -y

• 检查安装，终端输入：hugo version

• 显示版本信息成功，即安装完成，显示信息类似如下：

  hugo v0.145.0 linux/amd64 BuildDate=unknown

注意：如果是CentOS 7，百分百会报错，因为官网下载的CentOS 7版本的GCC 都在 5 以下，版本太低了，这时候就需要手动安装GCC了，是不支持直接命令升级的，由此会引发一堆必要的不必要的问题。

2.Ubuntu

• 更新apt-get：sudo apt-get update

• 下载安装（默认标准版）：sudo apt-get install hugo -y

• 检查 Hugo 版本：hugo version

• 显示版本信息成功，即安装完成，显示信息类似如下：

  hugo v0.145.0 linux/amd64 BuildDate=unknown

注意：使用 apt-get install 方式安装的 Hugo 版本通常较旧，并且是 标准版，不支持 SCSS/SASS。

3.Mac

在 macOS 上，使用 Homebrew 安装 Hugo 是最简单的方法。Homebrew 默认安装的是 Extended 版本，支持 SCSS/SASS 处理，非常推荐！

• 更新 Homebrew：brew update

• 下载安装（默认拓展版Extended）：brew install hugo

• 检查 Hugo 版本：hugo version

• 显示版本信息成功，即安装完成，显示信息类似如下：

  hugo v0.145.0 linux/amd64 BuildDate=unknown

三、使用

1、创建站点

切换到需要创建站点的目录下执行：hugo new site 站点名 即可创建一个站点出来

站点的目录结构：

demo
├─archetypes
├─config.toml     配置文件(hugo.toml/hugo.yaml)
├─content         存放MD文件的目录
├─data
├─layouts
├─static
└─themes          模板目录

配置文件config.toml常用参数：

theme = "docport"                  模板
baseURL = "http://example.org/"    访问路径
languageCode = "zh-cn"             语言
title = "My New Hugo Site"         html页面的title标题
publishDir = "demo"                html静态资源生成的路径，默认是public下

2、模板

老版本配置文件一般config.toml，新版本的配置文件一般叫hugo.toml或者hugo.yaml

theme主题模板地址

此处以book模板为例：book的theme模板地址

3、安装模板和运行的三种方式

1.方式一：git submodule（git 子模块安装）

需要安装git工具

• 创建站点命令是：hugo new site 站点名

• 如上就切换到 cd 站点名 目录下

• 执行命令，初始化项目：git init

• 执行命令：git submodule add https://github.com/alex-shpak/hugo-book themes/hugo-book

• 执行命令，复制md文件：cp -R themes/hugo-book/exampleSite/content.en/* ./content

• 复制配置文件，进入到示例demo项目的themes/hugo-book/exampleSite/目录下，复制hugo.yaml内容到demo目录下的config.toml或者hugo.toml，就是创建站点时默认生成的配置文件里面。

• 执行命令，本地运行站点示例1：hugo server --bind 0.0.0.0 --port 1313 --theme hugo-book

  默认运行端口是1313，可以--port指定运行端口，--bind指定运行ip，--theme指定运行模板

• 执行命令，本地运行站点示例2：hugo server --minify --theme hugo-book

  这个命令的作用是 启动 Hugo 本地开发服务器，并使用 hugo-book 主题，同时进行 HTML 代码压缩（minify） 以提高性能。

• 运行后即可浏览器访问，默认访问地址：http://localhost:1313/

• 打包生成html

  • 打包生成静态文件命令：hugo 或 hugo -t hugo-book等参数

  • 打包后的静态文件可以直接使用nginx配置访问

  • 文件目录结构会发生变化

    demo
    ├─archetypes
    ├─config.toml     配置文件(hugo.toml/hugo.yaml)
    ├─content         存放MD文件的目录
    ├─data
    ├─demo            会增加的新目录，配置里面配置的，生成的静态资源都存储在这里
    ├─layouts
    ├─resources       这个也是生成的目录
    ├─static
    └─themes          模板目录
    

    resources：文件夹是 Hugo 资源管理 机制的存储目录，它主要用于缓存 处理过的静态资源，包括 图片、SCSS、JS、字体 等。

2.方式二：hugo module（hugo 模块安装）

前提条件是需要安装go编译器，通过go编译器安装hugo

• 初始化hugo模块：hugo mod init github.com/repo/path

• 进入示例hugo项目demo的根目录并将[module]部分添加到hugo.toml中：

  [module]
  [[module.imports]]
  path = 'github.com/alex-shpak/hugo-book'
  

• 加载/更新主题模块：hugo mod get -u

• 执行命令，本地运行站点，运行命令如上：hugo server --minify

• 运行后即可浏览器访问，默认访问地址：http://localhost:1313/

• 打包生成html

  • 打包生成静态文件命令：hugo 或 hugo -t hugo-book等参数

  • 打包后的静态文件可以直接使用nginx配置访问

  • 文件目录结构会发生变化

    demo
    ├─archetypes
    ├─config.toml     配置文件(hugo.toml/hugo.yaml)
    ├─content         存放MD文件的目录
    ├─data
    ├─demo            会增加的新目录，配置里面配置的，生成的静态资源都存储在这里
    ├─layouts
    ├─resources       这个也是生成的目录
    ├─static
    └─themes          模板目录
    

    resources：文件夹是 Hugo 资源管理 机制的存储目录，它主要用于缓存 处理过的静态资源，包括 图片、SCSS、JS、字体 等。

3.压缩文件安装

• 下载压缩包

• 解压压缩包放到demo下的themes目录下

• 统一模板名称

  一般下载下来的压缩包解压后的目录名称都会携带-master等内容，例如：hugo-book-master

  打开themes/hugo-book-master/exampleSite下的配置文件hugo.yaml查看theme的值，修改目录名称保持和theme值一致。（一句话概括就是找到exampleSite下的配置文件的theme，修改其父级目录文件夹名称）

• 执行命令，复制md文件：cp -R themes/hugo-book/exampleSite/content.en/* ./content

• 复制配置文件，进入到示例demo项目的themes/hugo-book/exampleSite/目录下，复制hugo.yaml内容到demo目录下的config.toml或者hugo.toml，就是创建站点时默认生成的配置文件里面。

• 执行命令，本地运行站点示例1：hugo server --bind 0.0.0.0 --port 1313 --theme hugo-book

  默认运行端口是1313，可以--port指定运行端口，--bind指定运行ip，--theme指定运行模板

• 执行命令，本地运行站点示例2：hugo server --minify --theme hugo-book

  这个命令的作用是 启动 Hugo 本地开发服务器，并使用 hugo-book 主题，同时进行 HTML 代码压缩（minify） 以提高性能。

• 运行后即可浏览器访问，默认访问地址：http://localhost:1313/

• 打包生成html

  • 打包生成静态文件命令：hugo 或 hugo -t hugo-book等参数

  • 打包后的静态文件可以直接使用nginx配置访问

  • 文件目录结构会发生变化

    demo
    ├─archetypes
    ├─config.toml     配置文件(hugo.toml/hugo.yaml)
    ├─content         存放MD文件的目录
    ├─data
    ├─demo            会增加的新目录，配置里面配置的，生成的静态资源都存储在这里
    ├─layouts
    ├─resources       这个也是生成的目录
    ├─static
    └─themes          模板目录
    

    resources：文件夹是 Hugo 资源管理 机制的存储目录，它主要用于缓存 处理过的静态资源，包括 图片、SCSS、JS、字体 等。

注意：模板越复杂功能越多越容易出现如下这几类问题

• 情况一：有些时候只复制content下的文件是会有问题的，这时候就要看exampleSite下还有那些和demo下同名的文件夹，把内容拷贝过去即可
• 情况二：theme主题模板地址中的某些主题比较特殊可能引用第三方链接之类的东西，在运行时可能会因为网络问题导致报错，或者其它问题，这种情况需要自行查找问题。
• 情况三：hugo的版本问题，有些时候hugo的版本会导致出现一些样式之类的问题，当配置没有问题，文件没有问题的时候，出现样式错乱，和示例demo不一样的情况可以尝试更换hugo版本

四、避坑指南（使用注意事项）

在使用hugo命令生成静态文件的时候，确认hugo server运行没问题而出现以下情况：

• 出现一些没有修改的地方，样式或者内容莫名其妙的错乱了
• 页面链接错乱
• 跳转错乱
• 等相关或不相关的莫名其妙的问题

这种情况可以使用以下方式解决：

• 第一步：cd到项目目录下
• 第二步：执行缓存清楚命令：hugo --gc
• 第三步：忽略缓存，强制重新构建所有页面，执行命令：hugo --ignoreCache
• 注意：第二、三步可以合并到一起执行：hugo --gc --ignoreCache