Hugo 静态网站构建实战手册

快速开始

通过完整实践创建第一个 Hugo 站点，安装主题、编写内容、本地预览并生成静态文件

快速开始 #

这一节会从空目录开始创建一个 Hugo 站点，并完成主题安装、内容创建、本地预览和静态构建。你可以把它当作最小可运行流程，后续章节再逐步深入。

准备工作 #

确认已经安装 Hugo 和 Git：

hugo version
git --version

建议使用 Hugo Extended。官方 Quick Start 当前要求 Hugo v0.158.0 或更高版本；Hugo GitHub Releases 当前最新稳定版为 v0.163.0。如果使用第三方主题，也要查看主题 README 中的最低版本要求。

创建站点 #

hugo new site my-blog
cd my-blog
git init

执行后会得到一个基础项目：

my-blog/
├── archetypes/
├── assets/
├── content/
├── data/
├── i18n/
├── layouts/
├── static/
├── themes/
└── hugo.toml

安装主题 #

Hugo 可以不使用主题，但新手建议先从成熟主题开始。这里以 Ananke 为例：

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

修改 hugo.toml：

baseURL = 'https://example.org/'
title = '我的 Hugo 博客'
languageCode = 'zh-CN'
theme = 'ananke'

如果你使用 PrimeEdge，则把主题名和主题仓库替换为对应值：

theme = 'PrimeEdge'

创建首页 #

hugo new content _index.md

编辑 content/_index.md：

---
title: "首页"
description: "我的 Hugo 站点"
---

# 欢迎来到我的博客

这里会记录技术、生活和长期学习笔记。

创建第一篇文章 #

hugo new content posts/my-first-post.md

编辑 content/posts/my-first-post.md：

---
title: "我的第一篇 Hugo 文章"
date: 2026-06-10T10:00:00+08:00
draft: true
categories: ["Hugo"]
tags: ["静态网站", "博客"]
description: "记录 Hugo 建站的第一步"
---

## 开始写作

Hugo 使用 Markdown 编写内容，保存文件后本地预览会自动刷新。

## 为什么选择 Hugo

- 构建速度快
- 部署简单
- 内容可以用 Git 管理

draft: true 表示草稿。开发预览时可以显示，正式构建默认不输出。

本地预览 #

hugo server -D

打开浏览器访问：

http://localhost:1313

常用参数：

# 显示草稿内容
hugo server --buildDrafts

# 显示未来发布日期的内容
hugo server --buildFuture

# 指定端口
hugo server -D --port 8080

# 允许局域网访问
hugo server -D --bind 0.0.0.0 --baseURL http://你的局域网IP:1313

# 禁用快速渲染，排查模板缓存问题时有用
hugo server -D --disableFastRender

生成静态文件 #

正式构建：

hugo

启用压缩：

hugo --minify

输出目录默认为 public/：

public/
├── index.html
├── posts/
├── categories/
├── tags/
└── ...

把 public/ 中的文件部署到静态托管平台即可。

发布前处理草稿 #

正式发布前，记得把文章 Front Matter 中的草稿状态改掉：

draft: false

或者删除 draft 字段。正式构建默认不会输出草稿、未来日期内容和过期内容。

初始化远程仓库 #

git add .
git commit -m "Initial Hugo site"
git remote add origin https://github.com/你的用户名/my-blog.git
git push -u origin main

如果使用了 Git submodule，其他机器克隆项目后要执行：

git submodule update --init --recursive

常见问题 #

Q: 页面没有显示新文章

A: 检查是否是草稿、未来日期或过期内容。开发时用 hugo server -D -F -E 可以同时显示草稿、未来和过期内容。

Q: 主题没有生效

A: 检查 theme = '主题目录名' 是否和 themes/ 下的目录一致。如果主题是 submodule，运行：

git submodule update --init --recursive

Q: 样式丢失或路径异常

A: 检查 baseURL。本地开发一般不必强行设置成线上域名；部署前确保 baseURL 与线上地址一致。

Q: Windows 下命令报错

A: 优先使用 PowerShell、Windows Terminal、Git Bash 或 WSL。复制多行命令时注意换行符和反斜杠写法。

下一步 #

继续阅读 项目结构，理解 Hugo 为什么这样放文件。

评论

0%