我的Hexo博客搭好了03 - 搭建过程之：一路踩坑

文章系列导航

1. 第01篇 - 选择困难症发作
2. 第02篇 - 搭建过程之：披荆斩棘，晋级啦！
3. 第03篇 - 搭建过程之：一路踩坑
4. 第04篇 - 备份Hexo博客的源码目录，上传到Gitee仓库
5. 第05篇 - 更换Hexo主题
6. 第06篇 - 怎么给文章分类、打标签、展示目录
7. 第07篇 - 怎么制作/about/、/categories/、/tags/页面
8. 第08篇 - 让世界找到我——SEO大冒险(站点地图制作和提交)
9. 第09篇 - 添加统计字数和阅读时长的插件
10. 第10篇 - 怎么插入图片和视频
11. 第11篇 - 怎么创建文章系列导航
12. 第12篇 - 自动提交URL到搜索引擎(IndexNow + Google Search Console)
13. 持续更新中...

---

搭建过程比较繁琐，我一路踩了很多坑。分享出来，希望你能少走弯路，一站到底。

1 BOSS战——神秘的“章鱼猫”

问题描述

接下来是把博客放到网上。我在GitHub上建了个仓库，名字必须严格遵守“用户名.github.io”的格式，不然不好使。配置好Hexo的设置后，我庄重地输入了部署三连：

hexo clean && hexo generate && hexo deploy

看着命令行滚动，我心里满是期待。打开我的专属网址……然后我就看到了它：一屏由各种符号和空格组成的、极其抽象的“章鱼猫”（GitHub吉祥物）。

我的博客呢？我那么大一个博客呢？

那一刻的心情，就像我精心准备了礼物送给朋友，结果他拆开一看，是个空盒子。

排查BUG

1. 看状态：GitHub说构建成功了。
2. 看仓库：文件好像也传上去了。
3. 看设置：啊哈！破案了！原来GitHub Pages默认从仓库的 /docs 文件夹里找网页文件，但Hexo把文件都生成在根目录。这两兄弟根本没对上暗号！

解决方案

进入 github.com/wittzh/witt… 仓库页面，进入Settings -> Pages，在Branch下的“Select folder”中，将 /docs 改成 / (root)，等了一分钟再刷新——我的博客，它活了！

2 设置[TOC]来文章目录，没用

问题描述

因为Hexo的文章全部是markdown格式，我想着按照markdown的语法，在文章中添加[TOC]来展示目录，但是没用。

排查BUG

查了资料发现，在 Hexo 中，[TOC] 默认是无效的，因为 Hexo 使用的 Markdown 渲染器不支持原生 [TOC] 语法。

不过，Hexo 已经内置了目录生成功能。只需要启用就行了。可以在文章中的 Front-matter 中配置，也可以在next主题目录中的 _config.yml 中进行全局配置。

解决方案

详细的配置方法，请参考我的另一篇文章：第06篇 - 怎么给文章分类、打标签、展示目录

3 文章目录的链接，点击无效

问题描述

在我的博客文章中，我启用了目录插件，期望能在文章中展示目录。但是，当我点击目录中的链接时，发现没有跳转。

排查BUG

各种排查，各种重新部署，都没有用。

一开始我使用的landscape默认主题，然后尝试了改为next主题，没用，又改为fluid主题，还是没用。

于是我担心是_config.yml中的设置错误了，一一将设置还原为默认值，结果还是没有用。

最后没办法了，我只能重新安装Hexo，然后从新开始搭建博客，这才解决了目录链接点击无效的问题。

我猜测是因为在一开始我让AI帮我做了一些配置，然后AI改了Hexo中的某些文件，导致了这个问题。

解决方案

重装Hexo。

4 文章的子目录的链接，点击无效

问题描述

在我的博客文章中，当我点击目录打开了子目录，然后点击子目录链接时，发现没有跳转。

排查BUG

可能是我在文章头部添加了标题 <div class="title">第03篇 - 搭建过程之：一路踩坑</div>，导致在渲染markdown目录时出错了。

解决方案

将所有的markdown标题的级别降低一级，就可以正常点击子目录链接了。总之，不要出现 一级标题，比如 # title1。