Hexo 博客部署指北

今天尝试部署 Hexo 博客，发现确实是十分的简明快捷，以后要多加使用

这次的部署过程中遇到了以下几个问题：

1. 无法上传到 Github

部署 Hexo 时，使用教程中说的 repository:

https://github.com/andybroker/andybroker.github.io.git

无法正确上传，后来用了

git@github.com:andybroker/andybroker.github.io.git

才正确，应该是直接使用 ssh 进行上传，故没有写账号密码的过程

2. 配置文件时语言选项

中文的选项不是 zh-Hans，而应该是 zh-CN，关于其他的一些语言可以在 themes 中看到，其他的一些配置也可以在 themes 里对应的主题的配置文件 _config.yml 中进行配置，languages 文件夹内容如下所示：

3. Hexo 修改主题

需要把主题先下载下来再进行配置使用

4. Hexo 的配置文件

其中的参数需要在冒号后空一格，不能直接连接冒号

5. 更换电脑时的操作（现在已经使用 Github 进行版本控制，外加使用 Github Action 进行自动发布，所以这个可以忽略了）

1. 安装 Node.js

   检查是否安装 brew

   brew -v

   安装 homebrew：

   ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

   安装 node：(如果之前已经手动安装过 node，再次通过 homebrew 安装往往产生冲突，可以先删除，如果是通过 homebrew 安装的，下发命令 brew uninstall node 即可，如果是通过安装包安装的，手动删除 node 的安装文件即可)

   brew link node
   brew uninstall node
   brew install node

   检查是否安装 node：

   node -v
   npm -v

   注意：安装 cnpm（npm 由于源服务器在国外，下载 node 包速度较慢，cnpm 使用国内镜像，下载速度较快）：

   npm install -g cnpm --registry=https://registry.npm.taobao.org

2. 安装 hexo:

   npm i -g hexo

3. 把博客文件从 git 上拉下来，或者用 iCloud 中的，基本上只要在 Mac 上更新博客，都可以直接用 iCloud 文稿中的文件，但是如果要更新 git 上的文件，就要先拉到本地，用 iCloud 的将其覆盖，再推到远端

遇到的一些问题

Hexo 使用了 Fluid 皮肤后，hexo g 关于高亮报错

TypeError: Cannot set property 'lastIndex' of undefined
    at highlight (/home/xxxx/Blog/xxxxx/highlight.js/lib/highlight.js:514:35)   

这是因为在你的博客中，在用代码段时没有指明语言，可以把部分文章移出文件夹，逐渐找出是哪一篇的代码段没有指明语言，处理后再移回来

相关链接

Hexo 升级问题

最近在整理自己的博客，看到 Hexo 版本是 3.9.0，最新已经去到 6.0.0 了，而我所使用的主题 Fluid 的相关配置在新版本 Hexo 上将会更加方便简洁，所以决定升级一波

按照 Google 得来的升级步骤，先执行如下指令

npm install -g hexo-cli

运行完毕，再输入 hexo version 查看版本，哦豁，还是 3.9.0，看来应该是只升级了 hexo-cli，并没有正确升级 Hexo，于是再次进行搜索，得到如下的步骤

先安装 npm-check 和 npm-upgrade

npm install -g npm-check npm-upgrade

安装完后，执行 npm-check 即可检查本地各插件版本情况

执行 npm-upgrade 可根据当前版本和最新版本比较，让用户确认和选择是否升级

若用户确认升级，则会自动把 package-lock.json 和 package.json 文件内容进行更新后保存，然后执行：

npm update -g --save 

上述命令执行完毕，则所有通过 npm-upgrade 确认的插件全部都升级到最新（包括 Hexo）

稍等片刻后，出现了一堆日志，诸如改变了多少个 package 之类的，应该是报告出错了，同时贴心地附上处理的指令 npm audit fix，这时查看一下 Hexo 版本，仍然没有变化，还是 3.9.0，看来的确是出现问题了，那就输入 npm audit fix 试试看，又稍等片刻后通过 hexo version 验证 Hexo 版本，已经更新到最新的 6.0.0 了

如果还遇到另外的问题，可以参考原文，另附查看 Node.js 版本的指令： node -v

Node 快速切换版本、版本回退(降级)、版本更新(升级)

最近遇到一些 node 的坑，对旧版博客皮肤不太满意，所以更换了现在的 fluid，之后发布的时候报错，一查发现是 node 版本过高了，需要回退到比较稳定的版本，这时可以借助 node 版本管理模块 n 来解决这个问题

# 安装
sudo npm install n -g

# 下边步骤请根据自己需要选择

# 安装稳定版
sudo n stable

# 安装最新版
sudo n latest

# 版本降级/升级
sudo n 版本号

# 检测目前安装了哪些版本的node
n

# 切换版本（不会删除已经安装的其他版本）
n 版本号

# 删除版本
sudo n rm 版本号

相关链接

npm 在 Mac 上的权限问题

最近又在升级 Hexo 和 Fluid 主题，发现用 Fluid 官方推荐的指令 npm install --save hexo-theme-fluid ，会报类似如下错误（下面的结果是我在 npm install -g npm-check npm-upgrade 尝试安装 npm-check 和 npm-upgrade 时报的，借来展示下）

lvqixing@lvqixingdeMac-mini HoshiBlog % npm install -g npm-check npm-upgrade
npm error code EACCES
npm error syscall mkdir
npm error path /usr/local/lib/node_modules/npm-check
npm error errno -13
npm error Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/npm-check'
npm error     at async mkdir (node:internal/fs/promises:852:10)
npm error     at async /usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:624:20
npm error     at async Promise.allSettled (index 0)
npm error     at async [reifyPackages] (/usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:325:11)
npm error     at async Arborist.reify (/usr/local/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:142:5)
npm error     at async Install.exec (/usr/local/lib/node_modules/npm/lib/commands/install.js:150:5)
npm error     at async Npm.exec (/usr/local/lib/node_modules/npm/lib/npm.js:207:9)
npm error     at async module.exports (/usr/local/lib/node_modules/npm/lib/cli/entry.js:74:5) {
npm error   errno: -13,
npm error   code: 'EACCES',
npm error   syscall: 'mkdir',
npm error   path: '/usr/local/lib/node_modules/npm-check'
npm error }
npm error
npm error The operation was rejected by your operating system.
npm error It is likely you do not have the permissions to access this file as the current user
npm error
npm error If you believe this might be a permissions issue, please double-check the
npm error permissions of the file and its containing directories, or try running
npm error the command again as root/Administrator.
npm error A complete log of this run can be found in: /Users/lvqixing/.npm/_logs/2025-11-28T04_14_13_814Z-debug-0.log

错误信息显示没有足够的权限在 /usr/local/lib/node_modules/ 目录下创建文件夹，我直接下载了 Fluid 的 release 包，解压复制粘贴到指定目录完成了更新。但是后续我更新 Hexo 时，还是遇到了权限问题，我直接在指令前方加了 sudo，临时解决了，又觉得很不优雅，于是我问了下 DeepSeek，展开了一些探索

首先我再梳理了一下 npm 和 Node.js 之间的关系，Node.js 是 JavaScript 的运行时环境，没有 Node.js，npm 无法运行，因为 npm 本身就是一个用 JavaScript 编写的、需要 Node.js 环境来运行的工具。而 npm 是包管理器，用于管理 Node.js 生态下的成千上万个开源代码库。只要你下载了 Node.js，就会有对应的 npm

而现在我的问题在于，直接从官网下载 Node.js 安装包时，Node.js 和 npm 会被安装在系统目录（比如 /usr/local/bin/node 和 /usr/local/bin/npm），全局包默认也安装在系统目录（比如 /usr/local/lib/node_modules/），而这些目录需要管理员权限（sudo）才能写入

所以 DeepSeek 推荐我使用 nvm（Node Version Manager）安装的方式，nvm 把一切都安装在我自己的用户目录下，所以没有了权限问题。而且 nvm 还可以很方便地管理不同的版本，官方给出的例子如下：

nvm allows you to quickly install and use different versions of node via the command line.

$ nvm use 16
Now using node v16.9.1 (npm v7.21.1)
$ node -v
v16.9.1
$ nvm use 14
Now using node v14.18.0 (npm v6.14.15)
$ node -v
v14.18.0
$ nvm install 12
Now using node v12.22.6 (npm v6.14.5)
$ node -v
v12.22.6

Simple as that!

确实是很 Simple 了

同理，使用上面说的 node 版本管理模块 n 可能也可以处理权限问题

Github Action Node 版本过低导致构建失败问题

我更新完 Node.js 之后，把代码推上去，发现构建失败了，报错如下：

Run hexo clean
ERROR Cannot find module 'fs/promises'
Require stack:
- /home/runner/work/HoshiBlog/HoshiBlog/node_modules/hexo-fs/node_modules/chokidar/index.js
- /home/runner/work/HoshiBlog/HoshiBlog/node_modules/hexo-fs/dist/fs.js
- /home/runner/work/HoshiBlog/HoshiBlog/node_modules/hexo/dist/hexo/index.js
- /opt/hostedtoolcache/node/12.22.12/x64/lib/node_modules/hexo-cli/dist/hexo.js
- /opt/hostedtoolcache/node/12.22.12/x64/lib/node_modules/hexo-cli/bin/hexo
ERROR Local hexo loading failed in ~/work/HoshiBlog/HoshiBlog
ERROR Try running: 'rm -rf node_modules && npm install --force'
Error: Process completed with exit code 2.

fs/promises 这个模块是在 Node.js v14.0.0 中才正式稳定下来的。从错误堆栈中可以看到，当前 Actions 环境使用的 Node.js 版本是 12.22.12。在这个版本中，fs 模块没有 promises 这个子模块，因此在加载 hexo-fs 和 chokidar 等依赖时就失败了，所以我需要在 GitHub Actions 配置文件中，将 Node.js 版本指定为 v14.0.0 或更高

看了一下我本地的 Node 版本，更新到 24.x 了，于是去 HoshiBlog/.github/workflows/main.yml 里面，把 node_version: [12.x] 改为 node_version: [24.x]，再推一次代码触发 Action 的构建，果然成功了

不断使用和尝试中，如果有新的坑会继续补充

• 从零搭建 hexo 参考文章，这个博主也是使用 hexo 的，可以多多参考
• Hexo 主题网站