Hexo 博客从 3.9.0 升级到 8.1.1 迁移记录

Published:

Hexo 博客从 3.9.0 升级到 8.1.1 迁移记录

1
2
3
4
5
最近迷上学习vibe coding，我在一个社区关注了几个人，基本每天都会去刷一下他们的更新，现在有了coding agent，想着用这个练练手，那是第一个vibe coding的项目。

上面的用户发帖监控的小网站做好之后，我心里盘算还有什么可以做的，就想到了我这个荒废很久的个人博客。启用第一件事，就是把hexo的版本更新，然后处理下可能的兼容性问题。做完之后，索性让模型帮我总结整个过程并记录下来，于是有了这篇博文。

随着传播媒介的快速变化和大家注意力越来越金贵，越来越少的人把时间投入个人博客上。但就像很久以前开这个博客的时候想的，主要是为了自己，为了那些随风而逝的岁月。

背景

原有 Hexo 博客基于 3.9.0 版本（2019年），Node.js 要求 6.9-8.0。当前系统 Node.js 为 v24.13.0，需要升级 Hexo 到最新版本。

迁移方案对比

方案 描述 优缺点
方案A：渐进升级 3.9 → 4.x → 5.x → 6.x → 7.x → 8.x 逐步升级 耗时长，每步都可能遇到问题
方案B：新建项目迁移 创建全新 Hexo 8.x 项目，只迁移文章和主题 快速干净，推荐

最终选择：方案B

迁移步骤

1. 环境检查

1
2
3
4
5
6
7
# 检查 Node.js 版本
node -v
# v24.13.0 ✅ 满足 Hexo 8.x 要求（需要 20.19.0+）

# 检查文章数量
find source/_posts -name "*.md" | wc -l
# 21 篇文章

2. 创建新项目

1
2
3
4
5
6
7
8
9
10
# 安装最新 hexo-cli
npm install -g hexo-cli@latest

# 创建新项目
hexo init githubPagesBlog-new
cd githubPagesBlog-new
npm install

# 安装部署插件
npm install hexo-deployer-git --save

3. 迁移内容

1
2
3
4
5
6
7
8
9
10
# 迁移文章
cp -r ../githubPagesBlog/source/_posts/* source/_posts/

# 迁移主题
cp -r ../githubPagesBlog/themes/damnclean themes/

# 迁移其他资源
cp ../githubPagesBlog/source/CNAME source/
cp -r ../githubPagesBlog/source/_drafts source/
cp -r ../githubPagesBlog/source/about source/

4. 配置站点信息

编辑 _config.yml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Site
title: popucui
subtitle: Stuff Related to Bioinformatics Computer and More
description: Bioinformatics | Computer
author: Jack
language: zh-CN

# URL
url: http://blog.popucui.com/
permalink: :year/:month/:day/:title/

# Extensions
theme: damnclean

# Deployment
deploy:
  type: git
  repository: https://github.com/popucui/popucui.github.io.git

5. 修复主题兼容性问题

Hexo 8.x 相比 3.x 有多处 API 变更，需要修改主题模板文件：

5.1 修复 page.each() 方法

文件: themes/damnclean/layout/_partial/archive.ejs

1
2
- <% page.each(function(item){ %>
+ <% page.posts.each(function(item){ %>

5.2 修复 URL 生成方法

涉及文件: 多个 .ejs 模板文件

1
2
- <%- config.root %><%- item.path %>
+ <%- url_for(item.path) %>

5.3 修复日期格式化

1
2
- <%= item.date.toDate().toISOString() %>
+ <%= item.date.toISOString() %>

5.4 修复 Archives 页面样式

文件: themes/damnclean/source/css/_partial/archive.styl

1
2
3
4
5
6
.archive
  article
    header
      padding-left 0
      .icon
        display none  // 隐藏遮挡标题的图标

6. 构建和部署

1
2
3
4
5
6
7
8
# 生成静态文件
npx hexo generate

# 本地预览
npx hexo server

# 部署到 GitHub Pages
npx hexo deploy

版本对比

组件 旧版本 新版本
Hexo 3.9.0 8.1.1
Node.js 要求 6.9-8.0 20.19.0+
hexo-deployer-git 0.0.4 4.0.0
hexo-renderer-marked 0.2.4 7.0.0
hexo-renderer-stylus 0.2.0 3.0.1

废弃的配置项

从 Hexo 3.x 到 8.x，以下配置项已废弃：

废弃配置 说明
auto_spacing 已移除
multi_thread 已移除
max_open_file 已移除
external_link: true 改为对象形式配置

常用命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 本地预览
npx hexo server

# 生成静态文件
npx hexo generate

# 部署
npx hexo deploy

# 一键生成+部署
npx hexo g -d

# 清理缓存
npx hexo clean

注意事项

  1. 主题兼容性: 旧主题需要修改模板文件才能在新版 Hexo 上运行
  2. 插件更新: 所有插件都需要更新到兼容版本
  3. 配置迁移: 不要直接复制旧配置文件，建议对照新配置模板逐项迁移
  4. 备份: 迁移前务必备份原项目

参考链接

迁移日期: 2025-03-26