Hexo 博客部署与重建记录

记录一下 Hexo 的完整部署流程，并不涉及具体的 Hexo 主题以及配置细节。

生成与部署逻辑

Hexo 是一个基于 NodeJS 的静态博客框架。首先梳理一下主要的工作逻辑：

在本地博客文件夹中，下载必要的 Hexo 组件并配置。
本地预览：执行 hexo server 启动本地预览，Hexo 会在本地开启一个网站，通过 http://localhost:4000 访问。
在 source/_posts 目录中添加或修改博客文件（markdown 格式）。
执行 hexo generate 生成静态网页，生成的静态网页及相关的所有资源都会存放在 public/ 目录下。
执行 hexo clean 清理本地缓存（包括 public/ 和 db.json 文件等），这种做法可以有效避免一些错误。
部署：
- 如果安装了第三方部署插件，可以执行 hexo deploy 部署到远程仓库，实质上是将 public/ 目录下的所有内容打包复制到一个 git 本地仓库，然后提交到指定的远程仓库
- 也可以用其它任意方式，把 public/ 目录打包复制到网站对应的目录下即可。

日常写博客的流程：

启动本地预览：hexo server
新建或修改博客文档
清理本地缓存：hexo clean
生成：hexo generate
部署

关于本地预览的补充说明：

在本地预览期间，Hexo 会持续监视博客文件变动并自动更新，无须重启服务器。
对于配置文件的修改则无法体现，必须重启本地预览才能生效。
本地预览与 public/ 目录无关。

本地搭建

准备工作

安装 Node.js，因为 Ubuntu apt 提供的 Node.js 版本太低，参考 Node.js 官网给出的命令进行安装

1	curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh \| bash

这里的 nvm 其实就是一个用于管理 Node.js 版本的 bash 脚本，在这个过程中会给 .bashrc 在最后添加了一段配置，因此需要重新加载才能生效。（nvm 和 Node.js 通常建议用户级的安装，不建议全局安装）

安装对应版本的 node

1	nvm install 22

查看本地已安装的 node 版本

nvm ls

还需要安装 pandoc 来支持 LaTeX 渲染，通过 apt 安装还是存在一样的问题——版本过低，可以从 pandoc 的 GitHub 仓库下载最新版文件，然后执行

1	sudo dpkg -i pandoc-3.7.0.2-1-amd64.deb

测试一下安装成功

pandoc -v

从零搭建

全局安装 hexo-cli

1	npm i -g hexo-cli

新建 blog 文件夹，在其中执行初始化（ hexo 要求必须在一个空文件夹里面进行初始化）

hexo init

使用 npm 安装 butterfly（butterfly 主题不会放置在 themes 文件夹下）

1	npm install hexo-theme-butterfly

在 _config.yml 中切换主题，本地即可正常测试运行。

在基本功能测试完成之后，就可以安装插件并且进行相应配置，目前使用如下的插件：

关于本地搜索，安装 hexo-generator-search
关于字数统计，安装 hexo-wordcount
支持 Latex，首先需要 root 安装 pandoc，然后卸载自带的 hexo-renderer-marked，安装 hexo-renderer-pandoc
关于置顶和隐藏，卸载自带的 hexo-generator-index，安装 hexo-generator-index-custom
关于外链，安装 hexo-filter-nofollow
关于 sitemap，安装 hexo-generator-sitemap
关于 footer，安装 hexo-butterfly-footer-beautify

如果 npm 下载的网络太慢，可以考虑配置镜像源

1	npm config set registry https://registry.npmmirror.com

迁移搭建

如果是迁移已有的 Hexo 博客的源代码仓库，就更加简单：在全局安装 pandoc 和 hexo-cli 之后，拉取之前的博客源代码仓库

1	git clone <remote-url>

进入仓库目录，下载依赖的插件（基于 packages.json 和 packages-lock.json）

1	npm install

然后就可以正常使用，例如开启本地预览

1	hexo server

package.json

这里记录一下目前的package.json（2025年12月1日）

{
  "name": "hexo-site",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "build": "hexo generate --silent",
    "clean": "hexo clean",
    "server": "hexo server",
    "prebuild": "hexo clean --silent && ./dev/mdcheck.py source/_posts",
    "postbuild": "./dev/update.sh",
    "update": "git add . && git commit -m \"auto update\" && git push"
  },
  "hexo": {
    "version": "7.3.0"
  },
  "dependencies": {
    "hexo": "^7.0.0",
    "hexo-abbrlink": "^2.2.1",
    "hexo-filter-nofollow": "^2.0.2",
    "hexo-generator-archive": "^2.0.0",
    "hexo-generator-category": "^2.0.0",
    "hexo-generator-feed": "^3.0.0",
    "hexo-generator-index-custom": "^1.1.1",
    "hexo-generator-search": "^2.4.3",
    "hexo-generator-sitemap": "^3.0.1",
    "hexo-generator-tag": "^2.0.0",
    "hexo-renderer-ejs": "^2.0.0",
    "hexo-renderer-pandoc": "^0.4.0",
    "hexo-renderer-stylus": "^3.0.0",
    "hexo-server": "^3.0.0",
    "hexo-theme-butterfly": "^5.4.3",
    "hexo-wordcount": "^6.0.1",
    "with": "https://registry.npmmirror.com/with/-/with-7.0.2.tgz"
  }
}

补充：有的教程中 npm 命令有 --save 选项，代表将模块保存到 dependencies，但是目前的主流版本中已经不需要这个选项，因为已经是默认行为。

更新记录

2024年5月10日更新：添加了 hexo-abbrlink 插件，为博客生成唯一的哈希值链接，不再依赖于路径。
2024年9月2日更新：添加了 hexo-generator-feed 插件，为博客提供RSS支持。
2024年12月18日更新：侵入式添加了随机封面图支持，在主题源文件中加了一个js脚本，在配置文件中也加入了相应配置，细节见下文。
2025年2月22日更新：Butterfly 的版本更新升级已经部分解决了图片的随机选择问题（但是仍然是静态的，即生成时随机确定，部署后不会随着刷新更改），而且为了优化图片加载速度，直接从栗次元 API 爬了几十张风景图，用作默认封面。
2025年7月28日更新：更新了包括 Butterfly 在内的各个工具/插件，实际上重新把源码放在了云服务器中，并且简化部署方式，移除了 hexo-deployer-git 插件。

远程部署

直接把源码仓库的 public/ 目录通过 rsync 同步到云服务器上对应的公开目录即可，这是最简单直接的部署方法。

update.sh

#!/bin/bash
set -e

SRC_DIR="/path/to/blog/public/"
DST_DIR="/path/to/open-dir/"

echo "$SRC_DIR -> $DST_DIR"
rsync -av --delete "$SRC_DIR" "$DST_DIR"

除此之外，还有一些基于 Git 的部署方式：

通过 Git 把 public 目录推送到 GitHub 仓库，利用 Github Pages 进行部署；
通过 Git 把 public 目录推送到私有服务器，结合 hook 脚本自动复制 public 目录到服务器的公开目录。

这些操作都需要引入除了源码仓库之外的其它 Git 仓库，可以利用 hexo-deployer-git 插件进行一些简化。（其实没必要）