「2023.001|CN」Hexo NexT 升级笔记

发表于 更新于 阅读次数： 本文字数： 1.7k 阅读时长 ≈ 6 分钟

升级的原因

以前的老 blog 是2016年使用 Hexo 和 NexT主题 搭建的，到2020年时这两个项目都有了巨大的变化，有了很多新的强大功能，所以在那时候更新过一次。

3年后的今天又到了值得更新的时候，与上次不同的是，这次与其说是更新，实际上是重新建站了，因为使用了新的 github 账号 pwnfan 和新的域名 pwn.fan。

关于老 blog 里的文章，我会搬运那些至今仍未过时的内容到新 blog 里来。

关于 pwn.fan

pwn 是网络用语，在网络安全圈尤为流行，通常指“突破、超越”的意思，pwn.fan 作为域名，代表一种“热衷于不断创新和突破”的黑客精神。

跟老 blog 有什么不同

  • 新 blog 使用了 github action：
    • 这样就可以只用向 blog 的源码 repo(私有) push 新的 blog 源代码，通过这个 repo 里已经配置好了的 github action，就会自动生成静态的页面后 push 到另一个 github page 所在的目录 https://github.com/pwnfan/pwnfan.github.io
    • 而老 blog 需要手动运行 hexo deploy 命令部署
    • 新 blog 使用了 github action 的方式来部署静态文件，不需要项目录中添加 CNAME 文件。而旧 blog 采用从分支部署的方式，再需用向目录中添加 CNAME 文件
      • 参考 Configuring a publishing source for your GitHub Pages site
      • 参考 Managing a custom domain for your GitHub Pages site
stateDiagram
state "github: blog/main" as s1
state "github: pwnfan.github.io/gh-pages" as s2
state "site: https://pwnfan.github.io" as s3
[*] --> s1: blog update commit
note right of s1: private
s1 --> s2: (through github action hook)\n1. build static pages\n 2. auto commit to
note right of s2: public
s2 --> s3: served by github
  • 启用了多语言（英日中），并计划写多语言文章。
    • 由于我在持续学习英语和日语，过去也尝试过写英文 blog，但使用多语言编写blog的工作量不小，保证高质量的翻译会花掉不少时间。而 ChatGPT 的出现使相对高质量的翻译的工作量减少了很多，所以之后我会尽量同时使用3种语言发布文章。
    • 如果您只想浏览某一种语言的文章，可以使用页面最下方的语言切换菜单来切换

升级中遇到的问题及解决办法

自己定制的404页面不生效

问题

当访问不存在的页面时，显示的是 github 的 404 页面，如下图：

解决方法

在 404 页面的 Front-matter 里添加 permalink: /404.html:

1
2
3
4
 
---
title: 404
permalink: /404.html
---
KRISTOF ZERBE404 Page in Hexo for GitHub Pages

如何在 sitemap 时忽略某些页面

问题

生成 sitemap 时需要忽略某些页面，比如 404 页面。但 Hexo 和 Next 文档中都没有相关内容

解决办法

翻了一下 Hexo 的源码，了解到 sitemap 生成功能是使用了插件 hexo-generator-sitemap，插件 README里写了如何忽略某些页面，在页面的 Front-matter 里添加 sitemap: false 即可：

1
2
3
4
5
 
---
title: lorem ipsum
date: 2020-01-02
sitemap: false
---
hexo-generator-sitemap, READMEExclude Posts/Pages

多语言问题

请参考我针对多语言问题另写的一篇文章 「2023.002|CN」Issues系列：关于 Hexo 及 NexT 主题的多语言支持

Google Analytics

存在设置后不生效，无法通过 Google Analytics 统计阅读次数多问题。

分析原因，是由于 Google Analytics 已经升级到v4版本，tracking_id 的格式已变为 G-XXXXXXXXXX，而旧版本格式是 UA-XXXXXXXXX-X，具体可以参考这里。

如果按照 NexT 官方文档设置如下：

1
2
3
4
# Google Analytics
google_analytics:
  tracking_id: UA-XXXXXXXX-X
  only_pageview: false

是没有问题的。

但是如果我们将 only_pageview 去掉，或者设置为 true，则无法支持最新的v4版本的tracking_id的，后来我确认了一下相关源码，确实是这样的。NexT官方文档里目前没有专门指出这个问题，也有人提出过相关的 issue。

根据 [GA4] Introducing the next generation of Analytics, Google Analytics 4 里的说明可以知道，Google 将在2023年7月1日停止对旧版本的 Google Analytics 的支持，这意味着届时使用 UA-XXXXXXXXX-X 这种旧的版本的 Google Analytics 的 tracking_id 的网站将不再能够利用它进行数据统计。建议大家自查上面讨论的相关配置，确保自己的 blog 届时功能正常。关于这个问题也有其他网友讨论过，可以参考 [實作筆記] Hexo 更新 Google Analytics 4

Firebase 配置问题

Next 官方文档针对 Firebase 配置 的描述几乎是一笔带过，然而实际的设置比较复杂，我遇到了各种问题。这里给出我找到的解决办法的文章，具体问题就不再一一讨论了：

  • Hexo - Add View Count based on FireBase
  • Application Note #4 - Configure hexo-theme-next
  • 【2021年最新】React×firebaseにて「Uncaught (in promise) FirebaseError: Missing or insufficient permissions.」エラーが出力される原因とその対策
  • 【解決】FirebaseError: Missing or insufficient permissions.
  • https://firebase.google.com/docs/firestore/security/get-started?hl=en&authuser=0#deny-all
  • Structuring Cloud Firestore Security Rules
  • Fix: 'The Cloud Firestore API is not available for Datastore Mode projects.'

这里专门说一下其中涉及到的几个问题。

第一个，Firestore Database 默认工作模式是 Datastore mode ，所以文章阅读统计之类的信息在 Firebase 的主界面 Firestore Database 里看不到的，而是藏在 Google Cloud 中，这里直接给出：https://console.cloud.google.com/firestore/databases/-default-/data/panel/。

第二个，Firebase Database role 的写法可能引发安全问题，我这里给出根据 Firebase 官方文档的安全写法，其中的 articles 是你创建的 collection 名：

1
2
3
4
5
6
7
8
rules_version = '2';
service cloud.firestore {
  match /databases/{database}/documents {
    match /articles/{article} {
      allow read, write;
    }
  }
}

Github Action 问题

前文提到我使用了 github action 来做 CI/CD，为了避免重复造轮子我直接使用了 sma11black / hexo-action，它是用于自动化部署的 Hexo CI/CD Action。

实际使用时发现在build的时候会报错 [hexo-renderer-pandoc] pandoc exited with code null.

根据 NexT主题文档，渲染数学/化学等科学公式的引擎有两个可供选择：

  • MathJax
    • 它需要依赖于 hexo-renderer-pandoc
  • KaTeX

对比二者后，我选择使用的是 MathJax，在配置文件里设置为它，且在本地安装了 hexo-renderer-pandoc。

问题出现在 sma11black / hexo-action 制作的 docker 镜像中没有安装 hexo-renderer-pandoc，造成为的 blog 通过它编译的时候会因为缺少 hexo-renderer-pandoc 而失败。

我在自己fork的仓库 pwnfan/blog-github-action 中 修复了pandoc的问题。