快速入门
本章将带你从零开始创建一个 Hugo 网站并在几分钟内运行起来。按照步骤操作，你将掌握 Hugo 的基本工作流程。
前置准备
在开始之前，请确保你的系统已经安装了以下工具：
安装 Hugo
Hugo 提供预编译的二进制文件，安装非常简单。
Windows
使用 Chocolatey 安装：
choco install hugo-extended
或使用 Scoop 安装：
scoop install hugo-extended
也可以直接从 Hugo Releases 下载 ZIP 文件，解压后将可执行文件放到 PATH 目录中。
macOS
使用 Homebrew 安装：
brew install hugo
Linux
使用 Snap 安装：
sudo snap install hugo
或从 Hugo Releases 下载对应架构的 DEB 或 RPM 包。
安装 Git
Hugo 的主题管理依赖 Git，请确保已安装：
git --version
如果未安装，请从 git-scm.com 下载安装。
验证安装
运行以下命令验证 Hugo 安装成功：
hugo version
输出类似：
hugo v0.121.1-00b46fed8e4f8d88c6733c6b4d0b3f8e9e9e9e9e+extended windows/amd64 BuildDate=2024-01-01
建议安装 Hugo Extended 版本，它支持 SCSS/Sass 编译，这是许多主题需要的特性。
创建站点
使用 hugo new site 命令创建一个新站点：
# 创建名为 myblog 的站点
hugo new site myblog
# 进入站点目录
cd myblog
Hugo 会创建以下目录结构：
myblog/
├── archetypes/
│ └── default.md
├── assets/
├── content/
├── data/
├── layouts/
├── static/
├── themes/
└── hugo.toml
此时站点只是一个空壳，还需要添加主题和内容才能正常运行。
安装主题
Hugo 主题可以从 themes.gohugo.io 浏览选择。这里我们使用 Ananke 主题作为示例。
方法一：使用 Git 子模块（推荐）
# 初始化 Git 仓库
git init
# 添加主题作为子模块
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke.git themes/ananke
子模块方式的好处是可以通过 git submodule update 更新主题，同时保持主题版本可控。
方法二：使用 Hugo Modules
Hugo Modules 是更现代的依赖管理方式：
# 初始化模块
hugo mod init github.com/yourname/myblog
然后在 hugo.toml 中添加：
[module]
[[module.imports]]
path = 'github.com/theNewDynamic/gohugo-theme-ananke'
启用主题
编辑 hugo.toml 文件，添加主题配置：
baseURL = 'https://example.org/'
languageCode = 'zh-cn'
title = '我的新博客'
theme = 'ananke'
创建内容
使用 hugo new 命令创建新文章：
hugo new content content/posts/my-first-post.md
Hugo 会在 content/posts/ 目录下创建文件，并自动填充 Front Matter：
+++
title = 'My First Post'
date = 2024-01-14T07:07:07+01:00
draft = true
+++
编辑文章内容
打开文件，添加一些 Markdown 内容：
+++
title = '我的第一篇文章'
date = 2024-01-14T07:07:07+01:00
draft = true
categories = ['技术']
tags = ['Hugo', '教程']
+++
## 引言
这是我使用 Hugo 创建的第一篇文章。Hugo 是一个强大的静态网站生成器。
## 为什么选择 Hugo？
- **速度快**：Hugo 是世界上最快的静态网站生成器
- **简单易用**：单一二进制文件，无需复杂配置
- **灵活强大**：支持多语言、主题、短代码等功能
## 下一步
继续学习 Hugo 的更多功能，创建属于你的网站！
[访问 Hugo 官网](https://gohugo.io/)
关于 draft 参数
注意 draft = true 表示这是一篇草稿。默认情况下：
hugo命令不会构建草稿内容hugo server默认也不显示草稿
要预览草稿内容，需要添加 -D 参数：
hugo server -D
启动开发服务器
Hugo 内置了开发服务器，支持实时热重载：
# 启动服务器（不包含草稿）
hugo server
# 启动服务器（包含草稿）
hugo server -D
# 允许局域网访问
hugo server --bind 0.0.0.0
终端会输出类似信息：
Start building sites …
hugo v0.121.1-00b46fed8e4f8d88c6733c6b4d0b3f8e9e9e9e9e+extended
| ZH-CN
-------------------+--------
Pages | 7
Paginator pages | 0
Non-page files | 0
Static files | 1
Processed images | 0
Aliases | 0
Sitemaps | 1
Cleaned | 0
Built in 28 ms
Watching for changes in myblog/{archetypes,assets,content,data,layouts,static,themes}
Watching for config changes in myblog/hugo.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: "hugo server --disableFastRender"
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
打开浏览器访问 http://localhost:1313/，你将看到新创建的网站。
开发服务器的优势
- 实时预览：保存文件后浏览器自动刷新
- 快速构建：增量构建，只处理修改的部分
- 错误提示：模板错误会直接显示在浏览器中
配置站点
编辑 hugo.toml 来自定义站点：
baseURL = 'https://example.org/'
languageCode = 'zh-cn'
title = '我的技术博客'
theme = 'ananke'
[params]
description = '分享编程技术、学习心得'
author = '张三'
[menu]
[[menu.main]]
name = '首页'
url = '/'
weight = 1
[[menu.main]]
name = '文章'
url = '/posts/'
weight = 2
[[menu.main]]
name = '关于'
url = '/about/'
weight = 3
创建关于页面：
hugo new content content/about.md
编辑 content/about.md：
+++
title = '关于我'
date = 2024-01-14T08:00:00+01:00
draft = false
menu = 'main'
+++
## 个人简介
你好！我是一名软件开发工程师。
## 联系方式
- GitHub: [github.com/yourname](https://github.com/yourname)
- Email: [email protected]
发布文章
当文章完成后，将 draft 设置为 false：
+++
title = '我的第一篇文章'
date = 2024-01-14T07:07:07+01:00
draft = false # 改为 false
+++
构建站点
使用 hugo 命令构建静态站点：
# 基本构建
hugo
# 压缩输出
hugo --minify
# 清理未使用的资源
hugo --gc
# 组合使用
hugo --gc --minify
构建完成后，所有静态文件会生成在 public/ 目录：
public/
├── index.html
├── index.xml # RSS 订阅
├── sitemap.xml
├── posts/
│ ├── index.html
│ └── my-first-post/
│ └── index.html
├── about/
│ └── index.html
└── ...
这个 public 目录就是可以部署到任何静态托管服务的完整网站。
部署站点
Hugo 生成的静态网站可以部署到多种平台。以下是几种常见的部署方式：
GitHub Pages
在项目根目录创建 .github/workflows/deploy.yml：
name: Deploy Hugo site to Pages
on:
push:
branches: ["main"]
workflow_dispatch:
permissions:
contents: read
pages: write
id-token: write
jobs:
build:
runs-on: ubuntu-latest
env:
HUGO_VERSION: 0.121.1
steps:
- name: Install Hugo CLI
run: |
wget -O ${{ runner.temp }}/hugo.deb \
https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.deb
sudo dpkg -i ${{ runner.temp }}/hugo.deb
- name: Checkout
uses: actions/checkout@v4
with:
submodules: recursive
fetch-depth: 0
- name: Setup Pages
id: pages
uses: actions/configure-pages@v4
- name: Build with Hugo
env:
HUGO_ENVIRONMENT: production
run: |
hugo \
--gc \
--minify \
--baseURL "${{ steps.pages.outputs.base_url }}/"
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: ./public
deploy:
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
needs: build
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
推送代码后，GitHub Actions 会自动构建并部署网站。
Netlify
在项目根目录创建 netlify.toml：
[build]
publish = "public"
command = "hugo --gc --minify"
[context.production.environment]
HUGO_VERSION = "0.121.1"
HUGO_ENV = "production"
[context.deploy-preview.environment]
HUGO_VERSION = "0.121.1"
连接 GitHub 仓库到 Netlify，每次推送都会自动部署。
Vercel
Vercel 会自动识别 Hugo 项目，无需额外配置。只需：
- 登录 Vercel
- 导入 GitHub 仓库
- 点击 Deploy
Vercel 会自动设置正确的构建命令和输出目录。
常用命令速查
| 命令 | 说明 |
|---|---|
hugo new site <name> | 创建新站点 |
hugo new content <path> | 创建新内容 |
hugo server | 启动开发服务器 |
hugo server -D | 启动服务器（包含草稿） |
hugo | 构建站点 |
hugo --minify | 构建并压缩 |
hugo --gc | 清理未使用资源 |
hugo version | 显示版本 |
hugo list drafts | 列出所有草稿 |
下一步
完成快速入门后，建议继续学习：
- 内容管理：深入了解 Front Matter、分类法、内容组织
- 模板系统：学习 Go 模板语法，自定义页面布局
- 主题开发：创建属于自己的主题
- 短代码：扩展 Markdown 功能