重建 Hexo 博客引起的奇幻漂流

本文最后更新于:2022年4月8日 凌晨

缘起:我的博客显示不正常

由于 jsDelivr 在某些省份被墙,而我的博客(以下简称 本博)所用的 Fluid 主题使用 jsDelivr 的 CDN 为部分静态资源文件加速,导致 本博 无法显示样式和特效。

(顺便说一句,Fluid 主题的 官网文档 在谷月姐所在的城市都被墙了)

Fluid 主题的作者提供了 解决方案,即更换 CDN 配置。

但是,我按照这个 解决方案,修改 _config.fluid.yml 文件,hexo s 或者 hexo g 总是报错。

我把主题升级到最新的稳定版 1.8.14,仍然报错。

实在不能忍,我决定重建博客!

重建博客

博客所在的目录改名为 old_blog 先。

创建新目录 kukmoon_blog,命令行执行 hexo init

把最新版 Fluid 主题解压复制到 themes 目录,把原来的 old_blog/_config.ymlold_blog/_config.fluid.yml 复制到 kukmoon_blog 目录。

用 Notepad++ 或者 diff 命令逐行比较旧版和新版主题的配置文件, 即 kukmoon_blog/_config.fluid.yml (旧版主题的配置文件)和 kukmoon_blog/themes/fluid/_config.yml(新版主题的配置文件),按照 kukmoon_blog/themes/fluid/_config.yml 新增和改动的配置项,修改 kukmoon_blog/_config.fluid.yml。直到 hexo s 预览不出错为止。

参照旧博客的 package.json,在 kukmoon_blog 目录里,用 npm 命令恢复以下插件:

npm i hexo-abbrlink -s
npm i hexo-deployer-git -s
npm i hexo-generator-feed -s
npm i hexo-generator-sitemap -s
npm i hexo-filter-nofollow -s

由于 Fluid 主题集成了 hexo-generator-search 插件,所以没有额外安装。

迁移 MarkDown 源文件。把 old_blog/source 目录整个复制到 kukmoon_blog/source,覆盖已有文件。博客重建结束,接下来要关联 GitHub,并且修改主题。

关联 GitHub

执行以下命令先:

cd ~/kukmoon_blog
git init
git config --global user.name Kukmoon
git config --global user.email kukmoon97@gmail.com
git remote add origin git@github:Kukmoon/kukmoon_blog

old_blog/.github 目录、old_blog/.gitignore 复制到 kukmmoon_blog 目录。

修改主题实现自定义效果

注入 CSS

以前尝试向 Fluid 主题注入 CSS,如果把 CSS 文件放在本地,用相对路径注入,死活不成功[1]

今天发现,确实是与 Fluid 主题版本过旧有关。升级了主题,用相对路径注入 CSS,就成功了。

在注入 CSS 时,只写主文件名,不写扩展名[2]。例如,要注入 themes/fluid/source/css/example.css,就要在主题配置中这样写:

custom_css:
  - /css/example

修改 post.ejs

我又重建了我之前对 Fluid 主题的三处修改:增加打赏模块[3]、增加分享到模块[1]、增加跳转提示[4]

修改了 post.ejs

CSS 的注入,没有修改 layout.ejs,而是修改了 _config.fluid.yml 中的 custom_css 段。导入本地文件,使用相对路径,而不是使用绝对路径。

JS 的注入,如果 _config.fluid.yml 中的 custom_js 段,可以成功注入到 <head>...</head> 段,但是不能执行 JS 语句,只能用 <script> ... </script> 代码在 post.ejs 中注入,原因未知。

关于跳转提示,上次的修改[4]没有引入条件判断,在每个镜像站的首页都显示同样的提示。我这次用 JS 获取当前页面的实际 URL,如果 host 是 blog1.kukmoon.com,就隐藏提示。

<p id="tip_for_jumping" class="note note-primary" style="font-size: 15px;"><a href="https://blog1.kukmoon.com/<%- page.abbrlink %>.html">请中国移动用户点击此链接访问本文的镜像 <span style="text-decoration:underline">https://blog1.kukmoon.com/<%- page.abbrlink %>.html</span> ,以免图文加载过慢。</a></p>  <!--自己添加的镜像跳转提示:开始-->        
<script> <!-- 如果不是镜像站 https://blog1.kukmoon.com,就在博文页面显示一个跳转到镜像站的链接。这次用 JS 来做。 -->
	var current_host = window.location.host;
	if (current_host == "blog1.kukmoon.com") {
		document.getElementById("tip_for_jumping").style.display="none";
	}
</script> <!--自己添加的镜像跳转提示:结束-->

我无论怎么试,也无法用 EJS 获取当前页面的 URL 。Hexo 本身的变量不包含页面的实际 URL,我也不会用 EJS 获取页面的 URL,也不会用 EJS 读取 JS 的变量。所以,我只能用纯 JS,而不是 EJS 来实现。

修改 layout.ejs

我又重建了我之前对 Fluid 主题的一处修改:在首页增加镜像站的链接[5]

强制推送到 GitHub

git push -u -f origin master

GitHub Action 部署出错 (1)

用 GitHub Actions 部署时,出问题了。安装 Hexo 时系统提示:

ERROR Cannot find module 'hexo' from '/home/runner/work/kukmoon_blog/kukmoon_blog'

经过反复尝试才发现,我手贱改了 kukmoon_blog/package.json 文件中的 Hexo 版本号。赶紧复原,问题解决。

复原成原来的版本号,一个是6.1.0,一个是6.0.0

node_module/ 目录可以不推送到 GitHub

我发现 hexo init 命令会自动生成 .gitignore 文件,并把 node_module/ 目录加入其中。经测试,这个目录即使不推送到 GitHub,博客也能用 GitHub Action 部署,所以可以不推送。但是我有多台电脑需要保持博客源文件的同步,为了保证在每台电脑上都能渲染和预览,我需要借助 GitHub 把这个目录同步到每台电脑,所以我还是把它推送到了 GitHub。

子模块

我手贱,把 kukmoon_blog/themes/fluid 目录删除了,然后从 GitHub 上 Fork 原版的 Fluid 主题,并把 Fork 的主题克隆到本地。然后,把我修改过的文件放进去。

我一共修改了八个文件:

  • modified: README.md
  • modified: README_en.md
  • modified: layout/layout.ejs
  • modified: layout/post.ejs
  • added: source/css/macpanel.css
  • added: source/css/social-share.min.css
  • added: source/js/jquery.min.js
  • added: source/js/social-share.min.js

在本地预览和生成都没问题,这就说明博客重建成功了。

然后,我要把重建的博客源文件推送到 GitHub。在 git add 时,它提示 theme/fluid 目录已经是一个 GitHub 仓库,将无法推送到 GitHub 的远程仓库,要求我要么把这个目录加为子模块,要么移除。

无奈之下,我在 kukmoon_blog 目录下执行 git submodule add -f --name fluid git@github.com:Kukmoon/hexo-theme-fluid.git themes/fluid 命令[6],强行把 themes/fluid 目录添加为子模块。本地预览和生成都正常。

GitHub Action 部署出错 (2)

但是当我把博客源文件推送到 GitHub 用 GitHub Actions 部署时,渲染 HTML 文件出错。Hexo 提示 err: Error [Nunjucks Error]: _posts/article.md [Line 35, Column 4] unknown block tag: note 。不能识别 MarkDown 源文件中的 Fluid 主题特色功能 note 关键字。很明显,这是我在自动部署脚本中调用的 checkout 脚本没有读取 Fluid 子模块导致的。

解决方案:修改 kukmoon_blog/.github/workflows/deploy.yml 文件,找到 actions/checkout@v2,为它加个参数 submodules: 'true' 即可[7]

- name: Checkout
  uses: actions/checkout@v2
  with:
    submodules: 'true'

注意:下次在别的电脑上首次克隆博客源文件时,记得给 git clone 命令加 --recursive 参数,连子模块一起克隆[8]如果不加这个参数,就不会克隆子模块到本地。

git clone git@github.com:Kukmoon/kukmoon_blog.git --recursive

结束

就这样,奇幻漂流结束了。有一点收获,我了解了 Hexo 博客迁移和重建的方法,学了用 JS 获取页面 URL、 if 判断、控制 HTML 页面可见性的方法,知道了什么是 Git 的子模块。

参考文献