Step 01 - 搭建环境准备

开始之前先把工具准备好。这套流程只依赖 Hugo 一个可执行文件，不需要安装 Node.js，也不需要数据库，整个过程都是本地生成静态文件。

1.1 下载 Hugo

• 打开 Hugo 的官方网站的 Releases 页面，选择与你的操作系统匹配的发行版下载，解压后得到一个可执行文件即可。

  Hugo 分为 standard 与 extended 两个版本。本站使用了 Stack 主题，主题里的样式文件需要 extended 版本才能正确编译，所以下载时请认准 extended。

• Windows 下载的版本文件名形如：hugo_extended_xxxx_windows_amd64.zip

解压之后你会得到一个单独的 hugo.exe，把它放在一个固定目录里，后面所有命令都在这个目录下执行。

Step 02 - 搭建博客

2.1 创建站点

1. 在一个你心仪的位置新建一个文件夹，把解压出来的 hugo.exe 移动进去，然后在该文件夹的地址栏输入 cmd 并按回车，唤起命令提示符

2. 在弹出的命令提示符窗口中输入 hugo new site xxx（xxx 换成你的站点文件夹名），创建站点目录

3. 进入刚创建好的目录，输入 cd xxx 切换过去，并把 hugo.exe 复制一份到该目录下

到这里，一个空站点就已经建好了。此时目录里会有 archetypes、assets、content、layouts、static 等文件夹，以及一个 hugo.yaml 配置文件。

2.2 引入 Stack 主题

Stack 是一款以阅读体验见长的 Hugo 主题，自带深色模式、目录、标签与归档页面，适合用来写技术笔记。

1. 在站点根目录下创建 themes 文件夹，把主题文件放进 themes/hugo-theme-stack 目录。

2. 在 hugo.yaml 中指定主题：

1
2
3
4
5

theme: hugo-theme-stack
title: 我的小站
baseurl: https://example.com
DefaultContentLanguage: Zh-CN
hasCJKLanguage: true

3. 把主题自带的 config.yaml 示例内容合并进站点根目录的 hugo.yaml，再按需修改站点标题、副标题、头像、导航菜单等字段。

2.3 写第一篇文章

在 content/post/ 下新建一个目录作为文章的资源目录，例如 content/post/hello-world/，在其中新建 index.md：

1
2
3
4
5
6
7
8
9

+++
title = '第一篇文章'
date = 2024-11-29T19:00:00+08:00
draft = false
tags = ["随笔"]
categories = ["生活"]
+++

这里写正文。

图片也可以直接放在同一个目录里，正文中用相对路径引用，Hugo 会自动处理尺寸与压缩：

1

![](cover.png)

2.4 本地预览

在站点根目录执行：

1

hugo server

终端会给出一个本地地址，浏览器打开即可实时预览。修改文件保存后页面会自动刷新，写完再按 Ctrl + C 停止。

2.5 生成静态文件

确认内容没问题后执行：

1

hugo

生成的整站文件会输出到 public 目录。这个目录里全是 .html、.css、.js 和图片，不依赖任何后端程序，直接丢到任意静态托管或 Nginx 的站点目录下就能访问。

Step 03 - 常见问题

样式没生效：大概率是用了 standard 版本，换成 extended 版本重新构建。

中文标题的文章链接变成一长串编码：在文章的 front matter 里加一行 slug，手动指定这段链接，可读性会好很多。

图片显示不出来：优先使用文章资源目录（page bundle）里的相对路径；路径中尽量不要出现 #、? 这类在 URL 里有特殊含义的字符，否则会被浏览器截断。

小结

整套流程的核心只有一句话：用 hugo new / 手写 Markdown 产出内容，用 hugo 生成 public，再把 public 交给任意静态服务器。搞清楚这条链路之后，主题怎么换、托管放在哪里，都只是替换其中一环而已。