快速开始

概述

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

准备工作

在开始之前,您需要完成以下准备工作:

安装必要工具

  1. 安装 Hugo

    • 推荐安装 extendedextended/deploy 版本
    • 通过运行 hugo version 验证安装是否成功
  2. 安装 Git

    • Hugo 项目通常需要 Git 进行版本控制和主题管理
  3. 熟悉命令行操作

    • 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"

下一步

完成快速开始后,您可以:

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

故障排除

常见问题

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

调试工具

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

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

文章导航

章节内容

这是章节的内容页面。

章节概览