Hexo个人博客搭建踩坑记

1   开发环境配置

1.1   安装Node.js和启用Yarn

下载链接：

• Node.js：推荐LTS长期版，不推荐用最新版，可能很多npm并未能适配新版。
• Yarn（<=v1.22.19才有编译好的安装包）：若要使用新版Yarn，则不需要下载离线包安装，通过Node.js的corepack启用即可。

启用Yarn：

• 通过Corepack启用Yarn（>v1.22.19，要求Node.js>=16.10）
• 通过离线包启用Yarn（<= v1.22.19）

1. 管理员终端运行命令启用：corepack enable，执行成功之后yarn命令即可系统全局正常调用。
2. 终端运行命令：yarn global bin，复制路径添加到用户的PATH环境变量中。（这一步一定需要手动添加路径，因为程序没有自动添加PATH变量）

下载安装Yarn离线包即可，程序会自动添加PATH环境变量（Yarn程序路径和Package二进制程序路径）。

1.2   yarn和npm部分对应命令

yarn命令	npm命令	说明
yarn init	npm init	初始化
yarn / yarn install	npm install	安装包
yarn add [package]	npm install [package] --save	安装包
yarn add global [package]	npm install -g [package] --save	全局安装包
yarn remove	npm uninstall	卸载包
yarn upgrade	npm update	更新包
yarn global dir	npm config get prefix	查看安装目录
yarn global bin		查看安装bin目录
yarn cache dir		查看缓存目录
yarn cache clear	npm cache clean	清除缓存目录

1.3   版本和包更新

站点配置文件_config.yml和主题配置文件_config.next.yml的更新改动项，通过查看Github仓库代码是否存在更新改动。

Next主题直接可通过package版本号更新即可。

yarn outdated # 检查已过时的包，并修改 package 中 dependencies 中相关版本号
yarn global outdated # 全局检查已过时的包（hexo-cli若已过时，可以先remove再add）
rm -rf node_modules # 删除包路径
yarn # 重新为项目安装包，实际等于yarn install（根据package.json安装）

1.4   npm源设定

yarn config get registry  // 查看当前npm源
yarn config delete registry // 重置为官方源
yarn config set registry https://registry.npmmirror.com  // 设置npm镜像源（原淘宝镜像源）

当前有效镜像链接：npm config set registry https://registry.npmmirror.com
已失效镜像链接：npm config set registry http://registry.npm.taobao.org

1.5   安装hexo和hexo-cli

在想要安装hexo的位置建立文件夹「hexo」，打开命令行终端，以此路径作为终端工作路径。然后执行下面命令（推荐全局安装）。

• 全局安装hexo-cli
• 本地安装hexo-cli

yarn global add hexo-cli # 全局安装hexo-cli脚手架
hexo init # 初始化hexo，克隆hexo-starter和默认landscape主题仓库
hexo s # hexo server，启用本地服务器，见：http://localhost:4000/

yarn add hexo-cli
node_modules/.bin/hexo.cmd init blog # init需要空文件夹，所以另外用文件夹「blog」来初始化hexo
cd blog
yarn add # 一般hexo init之后都会自动安装相关依赖。若没有自动安装时，则需要执行该条命令以手动安装依赖。
node_modules/.bin/hexo.cmd s

2   hexo配置

2.1   _config.yml

注：language根据主题设置，注意新版Next主题已经没有zh-Hans语言配置文件，设置中文简体请用zh-CN参数。
注：新版Next主题主仓库已从 iissnan 名下迁移至 theme-next 组织。
注：现阶段新版Next支持Font Awesome 5.13.0，而5.1.4旧版Next版本只支持Font Awesome 4.7.0

2.2   为Next主题引入Giscus评论系统

1. 前置条件准备：
   1. 点击安装Giscus APP，选择安装到自己Github账户下的博客仓库github.io（不用勾选全部仓库）。
   2. 启用博客仓库github.io中的Discussions功能。
2. 安装hexo-next-giscus插件：yarn add hexo-next-giscus
3. 在博客配置文件_config.yml中添加giscus配置项，具体配置项参数值可以通过Giscus官方配置页面查看（填好仓库地址，页面会检查该仓库地址是否符合要求）。选好各项配置项后，在启用 giscus小节中可以看到最终生成的配置项参数值，例如repo_id和category_id。页面 ↔️ discussion 映射关系（mapping）设置为pathname即可，该选项是用来控制创建discussion的名字，pathname就是博文在博客中的路径值。Discussion 分类（category）设置Announcements类型即可，该类型只有管理员（项目维护者）有权限管理操作。

giscus:
  enable: true
  repo: Mister-Kin/Mister-Kin.github.io # 请填入自己实际的博客仓库 # Github repository name
  repo_id: # 请填入自己实际的id # Github repository id
  category: Announcements # Github discussion category
  category_id: # 请填入自己实际的id # Github discussion category id
  # Available values: pathname | url | title | og:title
  mapping: pathname
  # Available values: 0 | 1
  reactions_enabled: 1
   # Available values: 0 | 1
  emit_metadata: 1
  # Available values: light | light_high_contrast | light_protanopia | light_tritanopia | dark | dark_high_contrast | dark_protanopia | dark_tritanopia | dark_dimmed | preferred_color_scheme | transparent_dark | noborder_light | noborder_dark | noborder_gray | cobalt | purple_dark
  theme: preferred_color_scheme
  # Available values: en | zh-CN
  lang: zh-CN
  # Place the comment box above the comments: top | bottom
  input_position: top
  # Load the comments lazily
  loading: lazy

2.3   为文章标题实现自动编号

2.3.1   CSS样式实现

该CSS样式仅针对hexo-theme-next主题优化，并且也会针对TOC目录项进行适配。

需要注意的是：计数器应在对应标签上层级的创建，计数器+1就在对应标签中执行。

.post-body, .post-toc{
    counter-reset: h1counter;
}
.post-body h1, .post-toc .nav-level-1{
    counter-reset: h2counter;
    counter-increment: h1counter;
}
.post-body h2, .post-toc .nav-level-2{
    counter-reset: h3counter;
    counter-increment: h2counter;
}
.post-body h3, .post-toc .nav-level-3{
    counter-reset: h4counter;
    counter-increment: h3counter;
}
.post-body h4, .post-toc .nav-level-4{
    counter-reset: h5counter;
    counter-increment: h4counter;
}
.post-body h5, .post-toc .nav-level-5{
    counter-reset: h6counter;
    counter-increment: h5counter;
}
.post-body h6, .post-toc .nav-level-6{
    counter-increment: h6counter;
}

.post-body h1:before, .post-toc .nav-level-1 a:before{
    content: counter(h1counter) "\0000a0\0000a0\0000a0";
}
.post-body h2:before, .post-toc .nav-level-2 a:before{
    content: counter(h1counter) "."counter(h2counter) "\0000a0\0000a0\0000a0";
}
.post-body h3:before, .post-toc .nav-level-3 a:before{
    content: counter(h1counter) "."counter(h2counter) "."counter(h3counter) "\0000a0\0000a0\0000a0";
}
.post-body h4:before, .post-toc .nav-level-4 a:before{
    content: counter(h1counter) "."counter(h2counter) "."counter(h3counter)"."counter(h4counter)  "\0000a0\0000a0\0000a0";
}
.post-body h5:before, .post-toc .nav-level-5 a:before{
    content: counter(h1counter) "."counter(h2counter) "."counter(h3counter) "."counter(h4counter) "."counter(h5counter) "\0000a0\0000a0\0000a0";
}
.post-body h6:before, .post-toc .nav-level-6 a:before{
    content: counter(h1counter) "."counter(h2counter) "."counter(h3counter) "."counter(h4counter) "."counter(h5counter) "."counter(h6counter) "\0000a0\0000a0\0000a0";
}

2.4   live2d的修正处理

参考链接："idle" 设置多个动作时每次加载只会执行其中一个动作，不会随机到别的动作

关于适配自动构建的两个解决方法：

• Github Action自动构建需要相应修改命令（比较繁琐，因此放弃）
• fork源码修改重新编译发布npm包（需要注册npmjs，发布全局包也需审核；使用个人仓库链接作为npm使用即可）

详细修改：

1. cModel.js line 369（注释掉原来的，再添加以下代码）

if (this.motions[motionName] == null)
{
    this.loadMotion(motionName, this.modelHomeDir + motionName, function(mtn) {
        motion = mtn;

        thisRef.setFadeInFadeOut(name, no, priority, motion);

    });
}
else
{
    motion = this.motions[motionName];


    thisRef.setFadeInFadeOut(name, no, priority, motion);
}

2. cManager.js line 89（注释掉原来的，再添加以下代码）

this.models[i].startRandomMotion(cDefine.MOTION_GROUP_FLICK_HEAD,
        cDefine.PRIORITY_NORMAL);

3. 修改两个文件的代码后，在live2d-widget路径下执行构建命令：npm run inst:dev和npm run build:prod

• yarn命令版本
• npm命令版本

yarn global add commitizen && yarn global add conventional-changelog-cli && yarn
./node_modules/.bin/webpack --env prod --progress --colors && ./node_modules/.bin/webpack --env prod --progress --colors --config webpack.config.common.js

npm run inst:dev
npm run build:prod

yarn版本详细命令可通过查看node_modules/live2d-widget/package.json包得知：

"inst:dev": "npm install -g commitizen && npm install -g conventional-changelog-cli && npm install"
"build:prod": "./node_modules/.bin/webpack --env prod --progress --colors && npm run build:module",
"build:module": "./node_modules/.bin/webpack --env prod --progress --colors --config webpack.config.common.js",

3   Github Action自动构建

3.1   以往编写actions测试的一些命令

Bash版本（ubuntu runner）：

export PATH="$PATH:$(yarn global bin)"
sed -i "s/GITHUB_ACCESS_TOKEN/$TOKEN_VALUE/g" ./_config.yml # g在s模式下会替换每个匹配字符串
sed -i "s/GITHUB_ACCESS_TOKEN/$TOKEN_VALUE/" ./_config.yml # 这个只会替换每行的第一个字符串

Powershell版本（windows runner）：

(get-content _config.yml) -replace "GITHUB_ACCESS_TOKEN", "$TOKEN_VALUE" | Set-content _config.yml
$env:Path += $env:localappdata/yarn/bin
$env:Path +=";C:\Users\runneradmin\AppData\Local\Yarn\bin"
stix_2_math_font_path=$(find / -name STIXTwoMath-Regular.otf 2>/dev/null)
cp -a $stix_2_math_font_path ./LaTeXFonts
wget -P ./LaTeXFonts https://github.com/stipub/stixfonts/blob/master/fonts/static_otf/STIXTwoMath-Regular.otf

4   hexo部署报错排查

4.1   postinstall: npm run build:highlight failed

问题现象：在操作更新hexo-renderer-marked，在使用yarn执行构建时候，出现报错：hexo-util: command failed. Command: npm run build:highlight。经过尝试全局单独安装hexo-util排查发现，"npm'is not recognized as an internal or external command.。

问题原因：安装node.js，由于未勾选启用npm模块，导致系统安装的node.js环境缺失npm，但由于新依赖包直接在包构建命令里面新增并写死了npm命令，导致无法正常构建。

解决方法：重新运行node.js安装包，选择「change」选项，启用npm模块。然后重新运行yarn构建。

4.2   Stylus for Node v14 'Accessing non-existent property' errors

问题原因：Node.js v14环境搭配出现该报错。

解决方法：
本地开发环境Node.js版本选择v12，可避免出现Stylus for Node v14 'Accessing non-existent property' errors。

4.3   stylus出现奇怪的依赖报错问题

问题原因：stylus的依赖问题。

解决方法1：

1. 更新hexo-renderer-stylus到v3.0.0以后（该版本默认子依赖stylus为v0.59.0）。
2. 更新hexo-theme-next到v8.17.0以后（解决 stylus 依赖问题 ——css 库依赖报错）。

解决方法2：
在package.json中用resolutions字段手动指定stylus依赖的版本。

"resolutions": {
    "stylus": "^0.58.1"
}

5   hexo插件

5.1   修复hexo-heading-index插件bug的记录

点击查看PR的具体修改内容。关于debug的思路：在updateHeadingIndexes函数前后分别输出对应的数据，然后对比内容查看数据具体存在什么问题。

var contentKeys = ['content', 'excerpt'];
contentKeys.forEach((contentKey) => {
    if ( contentKey == 'excerpt') {
        const fs = require('fs');
        fs.writeFile('D:/excerpt_before.txt', contentKey, err => {
        if (err) {
            console.error(err);
        }
        });
    }
    postInfo[contentKey] = updateHeadingIndexes(options, postInfo[contentKey]);
    if ( contentKey == 'excerpt') {
        const fs = require('fs');
        fs.writeFile('D:/excerpt_after.txt', contentKey, err => {
        if (err) {
            console.error(err);
        }
        });
    }
});

关于cheerio库的配置：配置 Cheerio

5.2   hexo-tag-mmedia插件替代方案<ifame>标签

用 <iframe> 在 HTML 中插入B站视频：

• https://perrykum.github.io/rtcls/study/bliframe/bliframe.html

5.3   hexo插件开发资料

• https://hexo.io/docs/plugins.html#Plugin
• https://jiangtj.com/articles/beechnut/hexo-next-injects/
• https://theme-next.js.org/docs/advanced-settings/injects
• https://jayshao.com/hexo-inject-css-js/
• https://frapples.github.io/articles/2016-09-21-6d0.html

6   参考文献

[1] npm 淘宝镜像最新官方指引（2023.08.31）[EB/OL]. https://zhuanlan.zhihu.com/p/653480874.
[2] postinstall: npm run build:highlight failes leaving full hexo install unusable...[EB/OL]. https://github.com/hexojs/hexo‑util/issues/9.
[3] Step-by-step[EB/OL]. https://yarnpkg.com/migration/guide.
[4] giscus[EB/OL]. https://giscus.app/zh-CN.
[5] Hexo评论系统对比推荐[EB/OL]. https://yzs020220.github.io/posts/44102.
[6] Hugo 博客引入 Giscus 评论系统[EB/OL]. https://www.lixueduan.com/posts/blog/02-add-giscus-comment.
[7] CSS技巧：利用counter-reset和counter-increment实现标题自动编号[EB/OL]. https://blog.csdn.net/qq_26822029/article/details/118864239.
[8] 使用 Node.js 写入文件[EB/OL]. https://dev.nodejs.cn/learn/writing-files-with-nodejs/.