从零开始的Hugo建站生活

2025-04-07

今天我将我的SakuraChiyo主题上传至Github了！为了庆贺其诞生，我写下本文，旨在帮助喜欢折腾的孩子借助Hugo来建立他们的网站（好比如帮助当年的自己一样）。

Hugo简介

Hugo是一个开源的静态网站生成工具（其他的还有像Jekyll、Hexo等等），用GO语言写成，号称渲染速度是世界最快（此前我只用过Hexo，确实比Hexo要快）。具体详情参看其官网。简单来说，Hugo是按照你所提供的模板主题（theme）和编写好的页面内容（content）渲染出一系列的.html .xml等可被浏览器识别的网页文件。主题是网站的骨骼，内容是网站的血肉。

下载Hugo有很多方法，具体可以参看官方文档。下面介绍我当时用的方法。

我操作系统是Windows 11，所以在官方的发布页（国内打开github可能会卡）找到最新版的Hugo（截至写本文时是v0.145.0），然后再找到适于windows系统的版本。这时又蹦出了extended amd64 arm64等不同选择。amd64 arm64好理解，就是根据你电脑的CPU架构来选择，一般来说Intel、AMD之类的就选amd64，苹果之类的就选arm64。extended就是在标准版Hugo的基础上多了一些功能（参考官网介绍），而对我个人来说标准版已经够用了。

下载得到一个几十MB的压缩包，解压会发现核心就一个Hugo.exe，属于是绿色软件了。后续会在命令行内运行Hugo，所以要把它的路径加入环境变量（environment variables），具体设置方法网上都有大量介绍。设置好后启动命令行，直接运行hugo version指令，检查是否安装成功。

Github Pages简介

简单来说，Github Pages根据GitHub上的存储库（repository）中的内容来发布网站，其服务器就是Github的服务器，所以是免费的。官网在这里，另外还有官方的中文版使用说明。详细展开太复杂我不想写了……毕竟涉及到Git、Github等（爱折腾的孩子不会被这一点困难就吓倒的），这里我推荐一本参考书：大塚弘记的《Github入门与实践》，很薄的小册子。

总之，我们需要做的是在Github上创建一个启用了Github Pages功能的存储库。

如果你有其他的平台和服务器来发布你的网站文件，那么你可以忽略上面的Github Pages。

开始编写网站

首先需要一副骨骼框架，也就是Hugo的主题。推荐新手先从使用别人写好的主题开始（这只需你会一点Markdown），以后再来慢慢摸索如何写自己的主题（这要求你至少拥有关于HTML，css甚至JavaScript的知识）。Hugo的官方主题社区有许多颜值出色的主题供你挑选，你也可以试试我刚刚做好的SakuraChiyo主题，这也是我的网站目前所使用的。

建立网站

进入cmd或者bash，在你确定好的路径位置运行以下的Hugo指令

1hugo new site MySite --format yaml
2# 将“MySite”替换为您自定义的网站名称
3# 推荐使用yaml格式，其可读性优于toml格式

Hugo会生成以下的文件结构：

 1MySite/
 2├── archetypes #文章模板文件夹
 3├── assets     #网站资源文件夹
 4├── content    #网站页面内容文件夹
 5├── data       #网站数据文件夹
 6├── i18n       #多语言翻译字典文件夹
 7├── layouts    #页面模板文件夹
 8├── static     #静态资源文件夹
 9├── themes     #网站主题文件夹
10└── hugo.yaml  #网站设置文件

导入主题

将你的模板放进MySite/themes文件夹中，并在MySite/hugo.yaml文件中设置网站主题。可以看到你下载的主题文件夹内也具有类似上面的文件结构，其实Hugo在生成网站时，会以你网站根目录下的这些文件夹里的内容为最高优先级来生成网站的架构，如果某文件夹为空，再检索主题文件夹里的对应内容作为备用，所以你可以在网站根目录下的这些文件夹里添加部分你自己的排版方案来覆盖主题文件夹里的预设方案。新手可以先保持网站文件夹的设置全部为空，全盘接受主题文件夹的预设，等熟悉后再作自定义微调覆盖。

以我的SakuraChiyo主题为例。下载解压后得到一个hugo-SakuraChiyo文件夹，将该文件夹放进MySite/themes文件夹中，并在MySite/hugo.yaml中设置theme: hugo-SakuraChiyo。

完善设置

要让Hugo能按照你选定的主题正确地将Markdown页面内容渲染成.html文件，还需要对hugo.yaml进行正确设置。对不同的主题，hugo.yaml的设置方法也不相同，具体得参考你所选主题的帮助文档。关于SakuraChiyo主题的设置方法，请参看这里给出的样例。

编写页面

Hugo默认所有的待渲染页面存放在MySite/content文件夹内部。在这个文件夹里新建一个名为index.md的Markdown文件，在里面设置好头部参数（front matter）后（具体设置也需参考所使用主题的帮助文档或示例），就可以愉快地随意写东西了。这个直接放在content文件夹下的index.md文件，一般会被Hugo当作网站首页的。如果是其他页面的index.md，一般要放在content的对应子文件夹里面，具体也需要参阅所使用主题的帮助文档或示例。

生成浏览器可识别的网站页面

在网站根目录位置MySite运行指令

1hugo server

如果不出错的话，Hugo会在该网站的根目录下生成一个名为public的文件夹，同时会提示Web Server is available at ***，即可利用浏览器在***地址处对Hugo刚刚生成的网站进行本地预览。检查没有问题后，运行

1hugo

然后public文件夹里的内容就是我们所需要的可发布网页文件。

发布网站

将这个public内的所有文件上传（或覆盖）到之前你创建好的Github存储库中。Github Pages，启动！

恭喜，你的网站已然上线！