个站 | 从零开始的Hugo博客建站

上周，本博客正式开张，发布了第一篇博文《个站 | N个博客建站方案，总有适合你的一款！》，顺便放了个卫星。

今天，说好的第二篇专讲Hugo建站过程的博文来了，卫星落地，可喜可贺。

由于我的建站过程几乎是完全按照友邻的安利和教程（再次感谢友邻！）一步步完成的，因此同样的内容本文不会重复，只会提及和我自己搭建Hugo博客过程中和友邻教程里不一样的和补充的部分。

安装部署Hugo

这部分和友邻的教程基本一致，唯一明显的区别是，原教程里需要用到GitHub Desktop和Git Bash的部分我都靠VS Code解决了，也没有配置SSH。

万能的VS Code

如果说几年前刚开源的VS Code还只是个空架子，比不上Sublime Text、Notepad等老牌IDE，那现在的VS Code在各类成熟完善的Extensions的加持下已经堪称万能了。

当前版本的VS Code发行版均带有Source Control，让你在本地端甚至不需要安装Git，就能进行基于Git的版本操作，也可以在不配置SSH的情况下对接本地和GitHub账号：当你第一次尝试push commit时，VS Code会跳出来一个弹窗，要求你在GitHub里第三方OAuth VS Code，authorize成功后会再跳出一个弹窗让你登录你的GitHub账号，顺利登录后，就完成了免SSH的授权过程，你可以从本地pull & push了。

缺点是，VS Code的Source Control需要在界面上点来点去，对新手友好，但对习惯command line的选手而言就过于繁琐了，因此我试了几次后还是换回了在VS Code的Terminal里使用Git Bash的方式。

期间遇到的问题：

Git Bash不在VS Code默认可选的Terminal中

确认Git Bash已正确安装（文件夹里右键检查Git Bash是否在列）、确认环境变量（Environment Variables）已经正确配置后，最后靠手动打开VS Code的Terminal Settings，在Terminal > Intergrated > Default Profile里选出Git Bash/bash解决。

如果实在找不到，可以文件夹右键打开Git Bash，或者用Windows原生cmd下位替代。
安装Hugo后执行hugo version命令，显示hugo command not found。

在VS Code中关闭当前Terminal（Kill Terminal）后重开一个即可解决。
pull & push时报错，显示Authentication failed

检查之后发现是VS Code 1.62.2本身的bug，降级or升级可以解决。

remote: Repository not found.
fatal: Authentication failed for 'https://github.com/....git';

静态网站部署托管

除了Vercel，Netlify也提供非商业免费托管部署。

顺便一提，一些2021年前的Hugo教程里会提到一个叫Zeit Now的平台，这个其实就是改名前的Vercel。

绑定Domain

因为更便宜，最后选择在Namecheap上购买Domain。

第一次自己配置Domain的朋友，如果打算选择与教程中不一样的平台，最好优先选择知名的那几个。一是大平台在help & support上会做得更好，二是如果碰到问题也更容易搜到解决方法。

另外要注意一点：在设置了Vercel DNS后，Domain的Nameserver已经变成了Vercel，因此后续一切基于DNS的操作（比如设置subdomain）都要在Vercel里进行。一开始我没意识到这点，在配置Google Analytic时，愣是在Namecheap后端折腾了好久后，才意识到我搞错地方了……

安装主题

人要衣装，佛要金装，博客也要theme来装。UI是网站最重要的门面，多花点心思总归没错。

选择一个喜欢的theme

Hugo站的装修大多在现有主题的基础上进行（除了能自己写主题的大佬），因此最好从一开始就选择一个自己足够中意的“地基”，节省后续修整的功夫。

GitHub上几个我觉得好看好用的Hugo主题：

慎用git clone和git submodule

不建议按照Hugo的官方建站指南的步骤用submodule安装主题，也不推荐用git clone。

Git对submodule/子模块的定义如下：

子模块允许你将一个 Git 仓库作为另一个 Git 仓库的子目录。它能让你将另一个仓库克隆到自己的项目中，同时还保持提交的独立。

是目录，而不是包。换句话说，使用submodule时，git并不是真的把该module加载到了当前repository中，而只是创建了一个指向该module repository的地址用于追踪，实际并不会记录本地在submodule里做的一切修改。如果在这时打开GitHub上的repository，会发现放置submodule的那个文件夹其实是空的。

但如前面所言，Hugo站的装修大多在现有主题的基础上进行。如果不能自由地修改theme文件，会是一个非常大的限制。因此，更简单的做法是直接把主题下载到本地，然后将整个文件夹作为repository的一部分commit到线上。

只有两种情况适合使用git submodule：一，theme所在的repository属于你（比如，fork原主题，然后把自己fork的repository作为submodule）；二、你不打算对主题进行任何修改。

补充：还有一种情况是，利用Hugo优先读取根目录的性质，在根目录里创建和主题目录里路径一致、文件名一致的文件（例：在layouts/_default里创建和themes/<theme-name>/layouts/_default/archives.html一模一样的archives.html），然后在根目录的同名文件里进行修改。这种做法可以避免修改源文件，是更正规的操作，不过过程会繁琐一些（要不停复制黏贴+保证文件同名同路径），另外要注意submodule的版本更新情况。

如果已经不慎用了submodule而且本地做了修改，可以用一个简单粗暴的办法补救：新建一个文件夹，复制原文件夹里的全部内容，然后用git submodule -f deinit <submodule>命令删掉submodule，再删掉.gitsubmodule文件，最后把config里的theme换成新文件夹的名字。

施工前期准备

新建立的博客都处于一穷二白空荡荡的状态（搬家除外），为了方便调试，需要一些样本做测试。

这些样本可以直接从主题里面找。绝大多数的主题里都会有一个exampleSite文件夹，用于存放Demo文件，把里头content文件夹里的东西全部复制到根目录下的content里，就是一批现成的测试样本。当然，装修完毕后记得删掉，用真正的博客内容替换。

接下来，可以开始动手装修啦！

建议把所有计划的装修项目做成一份To-Do清单，然后专门开一个branch用于装修。每完成一个项目，就在该branch commit一次，这样方便版本追踪，万一某个装修项目出错救不回来，可以很容易roll back到前一个版本。等装修完成、测试确认无误后，再把装修用branch merge到main branch中。

具体装修的部分，因为太过琐碎，涉及具体的coding，而且还没完全施工完，便不在此赘述，等之后单独开一个装修记录再细说（绝对不是鸽了）。

一篇博文的诞生

最后聊一聊，在静态博客没有原生后端CMS的情况下，用什么工具写博文。

码字用什么

Hugo使用Markdown，写作工具自然最好原生支持Markdown。

以下是我用过的Markdown写作工具&平台：

Typora

用过的最好看最优雅的Markdown编辑器，没有之一，强烈推荐给外貌协会的朋友们。

缺点是没有云端同步，而且只有电脑版本，需要搭配Google Drive、GitHub等可以当云盘用的存储工具。
Notion

多端云同步，原生支持Markdown格式，更方便的是Notion上的内容复制下来也是Markdown格式。

缺点是Notion上的格式有一部分和Hugo不兼容。比如，Notion只支持到H3，H4开始全部显示成####；Notion的quote内部不支持使用跨段标签。
VS Code

当然，可以选择继续使用VS Code的一条龙服务，直接在VS Code里用Markdown写作。搭配theme和各类Markdown Extensions后，UI也不会难看到哪儿去。

从草稿到发布

我目前的博客写作及发布流程是：

使用Notion整理素材+笔记+写作。
一篇博文完成后，打开VS Code，pull博客的最新版本到本地，checkout到专门的draft branch。
在content/posts里新建博文（手动新建或Hugo命令行新建均可）。
设置博文的Front Matter。
手动把博文内容从Notion复制到VS Code里，调整不兼容的格式。
本地hugo server命令预览效果，捉虫补漏。
确认没问题后，commit & push到GitHub上。
double check（这一步可以看Vercel上的branch预览），确认无误后把draft branch merge到main branch，正式发布。