快速开始

概述

Hugo 的快速开始流程旨在让你在短时间内建立一个功能完备的 Hugo 网站。这个过程强调了 Hugo 的核心优势——速度和灵活性，并通过实践步骤和必要的工具使用，使你能够迅速体验到这些特性。

准备工作

在开始之前，你需要完成以下准备工作：

安装必要工具

1. 安装 Hugo

   • 推荐安装 extended 或 extended/deploy 版本
   • 通过运行 hugo version 验证安装是否成功

2. 安装 Git

   • Hugo 项目通常需要 Git 进行版本控制和主题管理

3. 熟悉命令行操作

   • Windows 用户推荐使用 PowerShell 或 Linux 终端（如 WSL 或 Git Bash）
   • 避免使用命令提示符或 Windows PowerShell

创建站点

生成项目骨架

使用 Hugo 命令创建新站点：

hugo new site my-blog
cd my-blog

这将创建标准的项目目录结构，包括：

• archetypes/ - 内容模板
• assets/ - 资源文件
• content/ - 内容源文件
• data/ - 数据文件
• layouts/ - 布局模板
• static/ - 静态文件
• themes/ - 主题

初始化 Git 仓库

git init

添加主题

为了快速启动并体验主题功能，我们将主题作为 Git 子模块导入。以 Ananke 主题为例：

git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke

在站点配置文件中指定主题：

echo 'theme = "ananke"' >> hugo.toml

添加内容

创建新页面

使用 Hugo 命令创建新的内容文件：

hugo new posts/my-first-post.md

编辑内容

新创建的内容文件位于 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 部署配置

开发与测试

启动开发服务器

hugo server -D

-D 标志表示构建草稿内容。服务器会：

• 在本地构建网站并提供服务（通常在 http://localhost:1313）
• 监控项目目录中的文件变化
• 检测到变化时自动重建并实时刷新浏览器（LiveReload）

预览网站

在浏览器中访问 http://localhost:1313，你应该能看到：

• 使用 Ananke 主题样式的网站
• 你刚创建的第一篇文章

实时开发

尝试修改内容文件或配置，保存后浏览器会自动刷新，显示最新更改。

发布站点

准备发布

将草稿状态设置为 false：

---
title: "我的第一篇文章"
date: 2025-06-19T10:00:00+08:00
draft: false
---

生成静态文件

运行构建命令：

hugo

这会在项目根目录下的 public 目录中生成完整的静态网站，包括：

• HTML 文件
• CSS 和 JavaScript 文件
• 图像等静态资源

重要注意事项

• Hugo 不会自动清空 public 目录
• 构建时会覆盖现有文件，但不会删除旧文件
• 根据需要手动清理该目录以避免文件残留
• 默认情况下不包含草稿、未来或过期内容

性能考量

资源缓存

对于大型网站，建议：

• 将处理后的资源缓存目录 resources 纳入版本控制
• 避免在 CI/CD 工作流中重复生成资源
• 显著加快构建速度

环境变量

配置可以通过环境变量进行简化，特别适用于 CI/CD 部署：

export HUGO_BASEURL="https://yourdomain.com"
export HUGO_ENVIRONMENT="production"

下一步

完成快速开始后，你可以：

1. 探索主题定制 - 学习如何修改主题外观和行为
2. 深入内容管理 - 掌握 Hugo 的内容组织方式
3. 学习模板系统 - 了解 Hugo 的模板语法和结构
4. 配置多语言 - 如果需要多语言网站支持
5. 设置自动化部署 - 将网站部署到云服务平台

故障排除

常见问题

1. 页面不显示 - 检查 draft 状态是否设置为 false
2. 样式不正确 - 确认主题配置是否正确
3. 构建失败 - 检查 Hugo 版本和主题兼容性

调试工具

• 使用 hugo server --debug 获取详细日志
• 使用 hugo config 查看完整站点配置
• 使用 hugo list drafts 查看所有草稿文件

通过这个快速开始流程，你已经创建了第一个 Hugo 网站并体验了其核心功能。接下来可以根据需要深入学习 Hugo 的各个方面。