一个博客的重生：基于 `Hexo` 引擎的博客配置

Posted on 2021-04-03 Edited on 2024-10-13 Views: Word count in article: 5.1k Reading time ≈ 18 mins.

前言

首先要向关注我的读者们（假如有）道个歉，因为学业繁忙，一直都没有时间撰写新的文章。咕咕的日子里我也学到许多东西，近段时间尤其多，特别是环境的配置涉及到许许多多细枝末节的问题，而且其中有很多灵光一现的 debug 思维我觉得特别有价值且值得玩味。如果不写点东西记下来了话，大概将来就都忘了吧。综上，我更深刻地认识到写博客是开发者最好的学习方式，所以要陆陆续续地重新开始写文章了！

也正因此，今后的技术类文章会着重于记录调试、配置的细节，力求还原脑力劳动的思路，希望将来的我会感谢努力的自己！

新的 Gitee 账号和仓库

之前取的 username 是 SamuelHuang2019，这个用户名现在让我很不满意，原因有三：

有大写字母，实际上全部小写最好
不够 impressive，不能让人眼前一亮
不好记，特别是对外国友人，姓氏和数字都挺无厘头的

这可是人生大事啊！经过思考，取了一个新的 username，隆重介绍：

kommunium

这是一个生造的词，~~里面有 3 个 m 好像显得我很 m~~，它的主体取材自德语 Kommunism，翻译成英语就是 communism，这个大家自然都懂吧。至于词尾则是参考了 Chrome 浏览器的 Chromium 内核的命名方式，一般以 ium 结尾的会让人联想起是某种元素。最后合成的含义就是 “共产元素”，从内涵到形式都让人印象深刻！

其实改完之后也纠结过是不是其他的组合反而更好，比如 kommium（更短但是略带轻佻意），kommunisium（有个 s 在听起来更帅但是又太拗口了）之类，不过罢了罢了，这样也挺好的！

GitHub 提供的更改用户名服务还是不错的，只需要修改就好了，似乎也没见到次数限制。不过值得注意的是，更改用户名后，仓库链接会被重定向至新的位置，但用户主页链接并不会，这已经非常不错了。我的图床和静态博客都托管在 Gitee 上，相比之下码云就不太人性化，并不支持更改用户名，所以只能是选择新创建一个账号。

为了保证原有的图床链接仍然可以正常显示，不能直接注销原有的 Gitee 账号，而需要注册一个新的账号作为主力使用，此时则需要有邮箱和手机验证。好在这两者我也都还有余裕。

Gitee 提供了仓库转移给企业、组织、个人的选项，此时 “仓库的地址将变更至目标用户的命名空间下”，并不确定能否重定向到原来的位置。经过实测，转移仓库后，原有的访问链接就会变为 404，看来不得不暂时保留这个老号了。

此处还有一个隐含的担忧，也即 Gitee 有可能会对非活跃用户 / 仓库进行清理，如果影响到此前图床里的图片问题就相当严重了。不过在这之前应该会收到邮件通知，并不用过分担心。

接下来需要进行的是图床和博客仓库的迁移。图床还好，直接新建一个仓库进行全新的开始就好。为了之前的一些文章可以仍然通过链接进行访问，原有的博客仓库不能直接转移；如果直接进行 fork 的话，又会留下一个 fork 自某某账号的标记，不够 brand new；Gitee 貌似没有提供在某个仓库的基础上新建仓库的选项，于是选择采取最朴素的复制粘贴方式。

将来也许会考虑换成别的平台的图床，例如华为云的对象存储服务，现在正在做项目学校有给代金券，希望以后一直有得用，没有的话资费应该也不会太贵吧。

`Hexo` 引擎配置

参考：

零基础免费通过 hexo+github 快速搭建个人博客（超详细图解 + B 站视频讲解资源）：https://blog.csdn.net/weixin_44523860/article/details/104166671

以下是笔者进行博客迁移加升级的过程，如果你需要全新开始博客，实际上过程比这会更简便。

之前曾经挖过坑说要出一篇 Hexo 配置的文章，不过自然也是荒废了…… 这次要重新配置，所以做个简单的记录。安装 Node.js 和 Git，以及拉取仓库的部分都直接略过。

博客工作目录初始化

（Node.js 安装好之后）在命令行运行 npm install -g hexo 以安装 Hexo 引擎。

此处 -g 参数代表全局安装，对于只在一个文件夹里运行博客来说，其实不加这个参数也一样，但是选择全局安装会在某些时候带来便利。

完成后运行 hexo -v 检查安装结果，我却出现了一系列报错：

ERROR Cannot find module 'hexo' from 'C:\Users\Guanc\Documents\GitHub\kommunium'
ERROR Local hexo loading failed in ~\Documents\GitHub\kommunium
ERROR Try running: 'rm -rf node_modules && npm install --force'

其原因是，复制整个仓库时同时复制了根目录下的 package.json，这个文件中存放了 npm 此前安装过的 modules 的信息，但显然在新的环境中，这些 module 都还未被安装，自然会出现冲突，将这个文件删除就好了。（不过这个列表也可以作为安装了的包的目录备份）

虽然之前的目录里已经有了 Hexo 博客的各个 “部件”，也就是 scaffolds/、source/、themes/ 文件夹等，但是实测此时运行 hexo s 等命令并不能被识别，还需要再次进行初始化。初始化 Hexo 博客文件夹的一个大坑是，文件夹中必须是空的！ 一个比较好的解决方案是，先在一个空文件夹里运行 hexo init 命令进行初始化，再将初始化操作拉取的文件、安装的包等等全数复制到进行版本控制的 Git 文件夹里！（既然需要进行版本控制，则会有.git/ 文件夹，不可能满足条件，这也是最诡异的地方）。

附上一些常用的 npm 操作备查：

指令作用

npm install <package> 安装某个包，或升级某个包

npm uninstall <package> 卸载某个包

npm update <package> 升级某个包

npm list <package> [--depth <depth>] 列出安装的包]

此处若不给出深度，则默认深度为 0。一个包在安装时，往往也会安装其他的许多依赖，通过指定一个深度参数可以选择要列出的安装的包的层级深度。

在任意一个命令中添加 -g 参数则会在全局执行，若不添加则默认在 local，也就是当前目录执行。

添加 --force 参数则强制执行。

npm 升级所有可更新包：https://blog.csdn.net/weixin_34294649/article/details/89384922

指令	作用
`npm install <package>`	安装某个包，或升级某个包
`npm uninstall <package>`	卸载某个包
`npm update <package>`	升级某个包
`npm list <package> [--depth <depth>]`	列出安装的包]

此外，还需要补全博客里用到的模块（参考 package.json）。特别注意，这里要斟酌是否全局安装了！如果某些模块造成问题，只要删掉博客目录下的文件夹，就可以清除所有局域安装的包！而如果全局安装，就没那么容易解决了。

版本迁移

接下来需要将新旧博客目录里的文件夹、文件一一对比，确定有哪些修改需要从旧版本带到新版本。

安装了一系列模块之后，发现实际上过了这么久许多模块并没有大版本升级，不过 Hexo 引擎却是从 4.2.1 跳到了 5.0.0 版本。既然是从头来过了，那就整个全新的吧。实际上，升级的过程相当痛苦，因为过程当中需要反复比较新旧的异同……

结论如下：

scaffolds/ 目录下的模板文件没有变动，直接用原来的替换就好（如果有自定义模板的话）
source/ 目录的结构也没有改变，直接用原有的替换就好，千万不要误删原有的 source/ 文件夹！这里存的都是博客原稿！
themes/ 文件夹一定要非常慎重，因为主题的配置往往十分复杂，而在外观上花心思又是大家调教博客的一个重点，需要更细致地比对文件间的修改。不过，其中的默认主题文件夹倒是用处不大。
_config.landscape.yml 是默认的 landscape 主题的配置文件，用处不大，可以直接删掉。
_config.yml 是整个 Hexo 站点的配置文件，需要详细比对。
其余以.json 结尾的文件是由 Node.js 自己生成的，可以不去理睬，用新生成的就好，老版本中的可以直接删掉。

首先来比对_config.yml：

旧版本中对于 URL 的注释为 "## If your site is put in a subdirectory, set url as 'http://yoursite.com/child' and root as '/child/'"，而新版本则并没有关于 subdirectory 的提示，是已经解决了这个问题了吗？

新版本的配置文件在# Writing 一节加入了新的参数：

prismjs:
  enable: false
  preprocess: true
  line_number: true
  tab_replace: ""

看来这是一个代码高亮的工具，新版本的引擎支持更灵活优美的代码样式。

现在关于博文的修改时间设定也有更新：

# before
## Use post's date for updated date unless set in front-matter
use_date_for_updated: false

# now
## updated_option supports 'mtime', 'date', 'empty'
updated_option: "mtime"

我选择在# Pagination 中将 per_page 设置为 0 以取消分页，不然看长文要点很多次下一页很烦人。再下方的 theme 自然也是要改成自己使用的主题了的。最后，需要加入对博客部署、数学、字数统计和看板娘等插件的定义，这些都是默认配置文件中所不包含的

deploy:
  type: git
  repo: https://gitee.com/kommunium/kommunium.git
  branch: pages

# Mathjax
mathjax:
  enable: true

symbols_count_time:
  symbols: true
  time: false
  total_symbols: true
  total_time: false
  exclude_codeblock: false
  awl: 100

# Live2D
live2d:
  enable: true
  scriptFrom: local
  pluginRootPath: live2dw/
  pluginJsPath: lib/
  pluginModelPath: assets/
  tagMode: false
  debug: false
  model:
    use: live2d-widget-model-koharu
    # use: live2d-widget-model-z16
    # use: live2d-widget-model-hijiki
    scale: 1
    hHeadPos: 0.5
    vHeadPos: 0.618
  display:
    superSample: 2
    width: 180
    height: 360
    position: right
    hOffset: 50
    vOffset: -50
  mobile:
    show: true
    scale: 0.5
  react:
    opacityDefault: 0.7
    opacityOnHover: 0.2

这里的 live2d 看板娘是我自己偏好的配置。

除此之外，.gitignore 根据需求简单合并一下即可。到这里，引擎自身已经配置好了，可以先用默认主题检查一下效果。

土土的，但是能用，接下来考虑美化。

`NexT` 主题配置

NexT 主题灵活度高，配置好之后真的很好看，但是也真的很复杂，早在很久之前我刚开始入手 Hexo 静态博客的时候就已经听闻了主题迁移非常麻烦，现在再来挑战一下。

如果我没有猜测错，（可能是）原作者 [@issnan](http://theme-next.iissnan.com/ 更) 新到了 v5.1.4 版本，而后则是由 [@next-theme](https://github.com/next-theme/hexo-theme-next) 这个团队来进行维护了？（纯粹通过观察得到的猜想，具体情况也未知）写作这篇文章时，最新的一个版本正是前一天发布的 v8.3.0，而在我最初接触 Hexo 博客时，v7.x 就已经算是很新鲜的事物了，不禁感叹时过境迁呀……

使用 GitHub Desktop 拉取最新的主题到 themes/ 目录下，然后再配置文件里修改主题为对应的主题文件夹名，之所以用这个软件是方便后期拉取更新。先测试一下，发现现在运行时会打出很帅的 logo。

INFO  ==================================
  ███╗   ██╗███████╗██╗  ██╗████████╗
  ████╗  ██║██╔════╝╚██╗██╔╝╚══██╔══╝
  ██╔██╗ ██║█████╗   ╚███╔╝    ██║
  ██║╚██╗██║██╔══╝   ██╔██╗    ██║
  ██║ ╚████║███████╗██╔╝ ██╗   ██║
  ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝   ╚═╝
========================================
NexT version 8.3.0
Documentation: https://theme-next.js.org

接下来要进行的就是最艰巨的任务，调试主题，需要对比大量配置文件…… 首先，docs/ 和 languages/ 目录都是我完全没修改过的，直接删去旧版本即可。

此处一定要特别特别小心，主题目录内的_config.yml 是主题的配置，而根目录中的_config.yml 是 Hexo 引擎的配置，他们是不一样的，切记切记！

新旧版本主题的配置文件的一个大不同是，新版主题的 custom_file 几乎全部从.swig 格式转成了.njk 格式，好在此前我只修改了 styles.styl 这一处，且它并未受到版本更新的影响。

若我没记错的话，在老版本中，启用 style: source/_data/styles.styl 这一自定义文件，实际上真正在起作用的却是 source/_custom/custom.styl，曾经踩过的坑历历在目，不知道现在是否修复了这个 bug。

剩余的修改过于细致繁复，不在这里一一记录。现在墙裂建议新接触 Hexo 博客的伙伴，在配置主题等设置时，一定要在注释里加上一个星标，表面这个字段是否被手动更改过！

接下来则是对 source/ 目录下的 CSS 文件进行修改，主要的外观自定义其实都在这里完成。

image/ 目录下存储的是一些图片、图标，如果有自定义的用户头像、网页背景等需要进行覆盖。
其他的目录基本不会有改动
最关键就是_custom/ 下的样式文件（如果有），需要带到新版本里面去

其他的文件夹应该都不包含手动的配置，唯一重要的就是 custom.styl 了（如果之前配置过）。现在重启本地博客，发现样式没有改变，猜测是自定义样式文件的路径冲突问题在新版本里被解决了，于是依照新的要求更换目录和文件名到 hexo-theme-next/source/_data/styles.styl，但此时依然没有生效！

参考以下两篇非常细致的文章，它们真的给到我很大帮助，感谢作者。

数据文件：https://tding.top/docs/getting-started/data-files.html
Hexo-NexT 版本更新记录：https://tding.top/archives/2bd6d82.html

幡然醒悟原来此处_data/ 目录是在 Hexo 博客的根目录下的 source/ 文件夹里，而非主题的 source/ 文件夹下！并且，在更新版本的 NexT 主题中，提倡源代码与自定义配置进行分离的主题设置方式，这里我暂时选用 override: true，毕竟之前都已经把设置全复制一遍了。再次启动博客，此时已经可以正常显示背景。

与上述两篇文献有所不同的是，在 Hexo 5.0 以上，配置文件应命名为_config.next.yml。

既然已经能用了，赶紧 Commit Push 一下怕丢失进度。注意到现在的博客是在新的空目录下建的，不能进行版本控制，所以需要先拉取仓库，再将博客文件复制进去。

但是现在站点的 source/_data/ 下的配置文件完全不能起作用了！经过重新初始化站点、拉取主题等操作，亦然不能解决问题，实在不知道是怎么回事。只能采取原有的办法，使用主题文件夹下的配置文件了。

为了解决对主题文件夹进行版本控制的问题，决定重新采用子模块方式拉取主题。

git submodule https://github.com/theme-next/hexo-theme-next.git themes/hexo-theme-next

无法拉取子模块的解决方案

新建 hexo-theme-next 文件夹

手动将这个文件夹使用 git add 命令添加到版本控制中

再手动 discard 这个更改（如在 GitHub Desktop 中）

接下来可以拉取子模块

在 GitHub Desktop 里添加本地仓库，选择主题文件夹，直到这里 VSCode 才成功将其识别为 S>（子模块）。

~~猜测与文件追踪的缓存有关，尝试过一些网上的方案，但都没有成功，最后这样解决了 ……~~ 貌似只是因为我弄错了目录。

在拉取新的主题之后，Hexo 出现诡异的报错：

TypeError: Cannot read property 'enable' of undefined

经过对比，发现竟然是直接拉取主题仓库，和以子模块方式拉取的主题仓库里的_config.yml 文件有不同，导致某个属性没有被识别！实在是令人疑惑，不排除是之前的操作出现了问题，导致我使用了老版本的配置文件。

其他问题的修复

接下来需要解决大量文章的标题显示为 “未命名” 的问题，许多人反映升级到新版本 Hexo 后出现这个问题。这应该是由于在老版本中，文章标题默认为 Markdown 中#后的一级标题，而新版本中必须通过 front-matter 中的 title 属性进行指定。好在我太过低产，已有的文章并不多，直接全部声明一下标题好了。

参考 Hexo 使用 NexT 主题文章元数据设置 - 比如文章字数和阅读时长预测配置字数和阅读时间统计，虽然能显示，但是字数统计貌似不太对，可能无解，应该是将代码也计算在内的缘故，更改 awl 并未起作用。

启动自动截取的 auto_excerpt 选项后，亦然没有自动截取。此处还需要安装一个额外的模块。

npm install hexo-excerpt --save

一个奇怪的 “未命名” 文章出现在首页，其内容看起来像是某种样式配置文件，检查后发现是 Git Book 的产物，在站点配置文件内将其忽略即可。

Hexo 的 ignore 参数与.gitignore 不同，如果单纯输入一个文件名，并不会忽略掉所有该名称的文件，而只会忽略掉根目录下的该文件，因此有可能需要加上通配符。

Anyway，现在总算配置好博客了！

图片、图床和 `PicGo` 配置

安装 PicGo，并在 Gitee 上新建图床仓库，在个人设置中创建私人令牌供 PicGo 访问。

不过，到这里我突然意识到，为什么不直接使用博客目录的相对路径来插入图片呢？其实完全可以做到，唯一需要担心的就是在分享 Markdown 文件给其他人（或者上传到知乎等）时图片不能加载，不过这个也很好解决，因为可以批量地将相对路径替换为在 Gitee 上的图片路径。

使用 Gitee 作为图床的一个缺陷是，当图片的大小超过 1M 时，就不能直接在 Markdown 中访问到了，可以通过 PowerToys 工具提供的批量调整图片大小功能来解决。若要发布到知乎，可以采取以下步骤

撰写文章，图片位于../images/ 目录下
推送 master 分支到 Gitee（否则后续无法从外部访问图片）
替换文章中所有的](../images/ 为](../images/
将全文复制到 wamgEditor 中，链接为 https://www.wangeditor.com/
用 Markdown Here 插件将所有内容转换为 Markdown 样式
复制这些内容，粘贴到知乎中
撤回之前的替换

此处还有一个大坑，就是要以相对路径插入图片，必须要安装插件 hexo-renderer-marked，并且在站点配置文件中添加参数：

marked:
  prependRoot: true
  postAsset: true

至于是否选择需要新建 asset 文件夹，则看个人需求，但是上面三行代码是不得不加的，否则无法加载图片。

参看：hexo 博客如何插入图片

在测试这几行参数的时候，意识到 Hexo 站点配置文件更改之后，直接再一次 start 本地预览不一定能看到真正的更改，可能需要先进行一次 hexo clean，在调试的时候要注意这一点。

接下来就是配置 Hexo 的推送目标，安装 hexo-deployer-git 模块，打开 GiteePages 功能，推送静态博客……

根据过往的经验，如果不选择强制启用 https 可能会遇到一些问题。

前言