快速开始
概述
Hugo 的快速开始流程旨在让您在短时间内建立一个功能完备的 Hugo 网站。这个过程强调了 Hugo 的核心优势——速度和灵活性,并通过实践步骤和必要的工具使用,使您能够迅速体验到这些特性。
准备工作
在开始之前,您需要完成以下准备工作:
安装必要工具
安装 Hugo
- 推荐安装
extended
或extended/deploy
版本 - 通过运行
hugo version
验证安装是否成功
- 推荐安装
安装 Git
- Hugo 项目通常需要 Git 进行版本控制和主题管理
熟悉命令行操作
- Windows 用户推荐使用 PowerShell 或 Linux 终端(如 WSL 或 Git Bash)
- 避免使用命令提示符或 Windows PowerShell
创建站点
1. 生成项目骨架
使用 Hugo 命令创建新站点:
hugo new site my-blog
cd my-blog
这将创建标准的项目目录结构,包括:
archetypes/
- 内容模板assets/
- 资源文件content/
- 内容源文件data/
- 数据文件layouts/
- 布局模板static/
- 静态文件themes/
- 主题
2. 初始化 Git 仓库
git init
3. 添加主题
为了快速启动并体验主题功能,我们将主题作为 Git 子模块导入。以 Ananke 主题为例:
git submodule add https://github.com/theNewDynamic/ananke themes/ananke
在站点配置文件中指定主题:
echo 'theme = "ananke"' >> hugo.toml
添加内容
1. 创建新页面
使用 Hugo 命令创建新的内容文件:
hugo new posts/my-first-post.md
2. 编辑内容
新创建的内容文件位于 content/posts/my-first-post.md
,默认 draft
状态为 true
。编辑文件内容:
---
title: "我的第一篇文章"
date: 2025-06-19T10:00:00+08:00
draft: false
---
这是我的第一篇 Hugo 文章!
## 标题
Hugo 使用 CommonMark Markdown 规范,支持各种 Markdown 语法。
- 列表项 1
- 列表项 2
- 列表项 3
**粗体文本** 和 *斜体文本*。
注意:新创建的内容文件默认为草稿状态(
draft: true
)。Hugo 在默认构建时不会发布草稿内容。
配置站点
基本配置
编辑项目根目录下的 hugo.toml
文件,设置基本信息:
baseURL = 'https://example.org/'
languageCode = 'zh-cn'
title = '我的 Hugo 站点'
theme = 'ananke'
[params]
description = "这是我的 Hugo 站点描述"
author = "您的名字"
配置原则
- 保持简洁配置,只定义与默认值不同的设置
- 主题作者通常会提供详细的配置指南
- 可以通过环境变量简化 CI/CD 部署配置
开发与测试
1. 启动开发服务器
hugo server -D
-D
标志表示构建草稿内容。服务器会:
- 在本地构建网站并提供服务(通常在
http://localhost:1313
) - 监控项目目录中的文件变化
- 检测到变化时自动重建并实时刷新浏览器(LiveReload)
2. 预览网站
在浏览器中访问 http://localhost:1313
,您应该能看到:
- 使用 Ananke 主题样式的网站
- 您刚创建的第一篇文章
3. 实时开发
尝试修改内容文件或配置,保存后浏览器会自动刷新,显示最新更改。
发布站点
1. 准备发布
将草稿状态设置为 false
:
---
title: "我的第一篇文章"
date: 2025-06-19T10:00:00+08:00
draft: false
---
2. 生成静态文件
运行构建命令:
hugo
这会在项目根目录下的 public
目录中生成完整的静态网站,包括:
- HTML 文件
- CSS 和 JavaScript 文件
- 图像等静态资源
3. 重要注意事项
- Hugo 不会自动清空
public
目录 - 构建时会覆盖现有文件,但不会删除旧文件
- 根据需要手动清理该目录以避免文件残留
- 默认情况下不包含草稿、未来或过期内容
性能考量
资源缓存
对于大型网站,建议:
- 将处理后的资源缓存目录
resources
纳入版本控制 - 避免在 CI/CD 工作流中重复生成资源
- 显著加快构建速度
环境变量
配置可以通过环境变量进行简化,特别适用于 CI/CD 部署:
export HUGO_BASEURL="https://yourdomain.com"
export HUGO_ENVIRONMENT="production"
下一步
完成快速开始后,您可以:
- 探索主题定制 - 学习如何修改主题外观和行为
- 深入内容管理 - 掌握 Hugo 的内容组织方式
- 学习模板系统 - 了解 Hugo 的模板语法和结构
- 配置多语言 - 如果需要多语言网站支持
- 设置自动化部署 - 将网站部署到云服务平台
故障排除
常见问题
- 页面不显示 - 检查
draft
状态是否设置为false
- 样式不正确 - 确认主题配置是否正确
- 构建失败 - 检查 Hugo 版本和主题兼容性
调试工具
- 使用
hugo server --debug
获取详细日志 - 使用
hugo config
查看完整站点配置 - 使用
hugo list drafts
查看所有草稿文件
通过这个快速开始流程,您已经创建了第一个 Hugo 网站并体验了其核心功能。接下来可以根据需要深入学习 Hugo 的各个方面。