Hexo个人博客搭建踩坑记

发表于 2024-02-02 更新于 2024-05-12 分类于 code 本文字数： 1.5k 阅读时长 ≈ 6 分钟

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）

管理员终端运行命令启用：corepack enable，执行成功之后yarn命令即可系统全局正常调用。
终端运行命令：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源设定

1
2
3

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

1
2
3

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 live2d的修正处理

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

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

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

详细修改：

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);
}

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

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

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

yarn命令版本
npm命令版本

1
2

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

1 2	npm run inst:dev npm run build:prod

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

1
2
3

"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）：

1
2
3

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版本选择v12，避免Stylus for Node v14 'Accessing non-existent property' errors。~~

5 参考文献

[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.