Hugo 静态网站构建实战手册

安装 Hugo

在 Windows、macOS、Linux 和 Docker 环境中安装 Hugo，并理解版本选择

安装 Hugo

Hugo 是一个单文件命令行程序。安装完成后，只要能在终端运行 hugo version，就可以创建、预览和构建站点。

官方 Quick Start 当前要求 Hugo v0.158.0 或更高版本。Hugo GitHub Releases 当前最新稳定版为 v0.163.0。实际项目中还要看主题要求：如果主题使用 SCSS、PostCSS、图片处理、Hugo Modules，建议安装 Hugo Extended。

选择版本

版本说明建议
Standard基础 Hugo，可构建普通站点只适合简单主题
Extended包含 Sass/SCSS 等扩展能力大多数主题推荐
Extended/deploy在 Extended 基础上包含 hugo deploy需要用 Hugo 内置部署命令时使用

一般用户直接安装 Extended 版即可。

Windows 安装

使用 winget

winget install Hugo.Hugo.Extended

安装后重新打开 PowerShell，验证：

hugo version

输出中建议看到 extended 字样。

使用 Chocolatey

choco install hugo-extended

手动安装

如果包管理器不可用，可以从 Hugo GitHub Releases 下载 Windows Extended 压缩包，解压后把 hugo.exe 所在目录加入系统 PATH。

检查路径：

where.exe hugo
hugo version

macOS 安装

使用 Homebrew

brew install hugo
hugo version

Homebrew 通常安装 Extended 版。若主题要求固定版本，可以在 CI 中固定版本，本地保持接近即可。

使用 MacPorts

sudo port install hugo

Linux 安装

Ubuntu/Debian

系统源里的 Hugo 版本可能较旧。新项目建议使用 Homebrew on Linux、Snap、Docker 或直接下载官方 release。

sudo apt update
sudo apt install hugo
hugo version

如果版本过低，改用 Snap：

sudo snap install hugo

或下载官方 release：

wget https://github.com/gohugoio/hugo/releases/download/v0.163.0/hugo_extended_0.163.0_linux-amd64.deb
sudo dpkg -i hugo_extended_0.163.0_linux-amd64.deb

版本号可以替换为当前官方稳定版。

Fedora

sudo dnf install hugo
hugo version

Docker 使用

如果不想污染本机环境，可以使用 Docker 构建：

docker run --rm -v "$PWD:/src" -w /src hugomods/hugo:exts hugo version

本地预览：

docker run --rm -it \
  -v "$PWD:/src" \
  -p 1313:1313 \
  hugomods/hugo:exts \
  hugo server --bind 0.0.0.0 -D

Windows PowerShell 写法：

docker run --rm -it `
  -v ${PWD}:/src `
  -p 1313:1313 `
  hugomods/hugo:exts `
  hugo server --bind 0.0.0.0 -D

同时安装 Git

大多数 Hugo 主题通过 Git 管理。建议同时安装 Git：

git --version

Windows 可以使用：

winget install Git.Git

macOS 可以使用：

brew install git

Linux 可以使用：

sudo apt install git

常用验证命令

hugo version
hugo env
git --version

hugo env 会输出 Hugo 版本、Go 版本、操作系统、模块状态等信息，排查构建问题时很有用。

版本固定建议

个人项目可以跟随 Hugo 稳定版升级，但部署环境建议固定版本，避免线上构建突然变化。

GitHub Actions 示例：

- name: Setup Hugo
  uses: peaceiris/actions-hugo@v3
  with:
    hugo-version: '0.163.0'
    extended: true

Netlify 示例：

[build.environment]
  HUGO_VERSION = "0.163.0"

Cloudflare Pages 可以在环境变量中配置：

HUGO_VERSION=0.163.0

常见问题

Q: hugo: command not found 或 PowerShell 提示无法识别命令

A: Hugo 没有加入 PATH，或安装后没有重新打开终端。先运行 where.exe hugo 或 which hugo 检查路径。

Q: 主题样式编译失败

A: 优先确认是否安装 Extended 版：

hugo version

如果输出没有 extended，重新安装 Extended 版。

Q: 本地能构建，线上失败

A: 检查线上 Hugo 版本是否和本地一致。很多部署失败都来自 CI 使用了过旧 Hugo。

下一步

继续阅读 快速开始，创建你的第一个 Hugo 站点。

评论

0%