Hexo 博客升级报告

Hexo 博客项目升级报告

升级概述

本次升级将项目从 Hexo 6.3.0 升级到 Hexo 8.1.1，并优化了主题管理方式。

主要升级内容

• Hexo 核心: v6.3.0 → v8.1.1
• 主题管理: 移除了 npm 安装的 hexo-theme-butterfly 依赖，完全使用本地自定义主题目录 (themes/butterfly/)
• 渲染器:
  • hexo-renderer-markdown-it: v6.0.1 → v7.1.1
  • hexo-renderer-pug: v3.0.0 → v3.0.0 (已是最新)
  • hexo-renderer-stylus: v2.1.0 → v3.0.1
• 服务器: hexo-server: v3.0.0 → v3.0.0 (已是最新)
• 部署器: hexo-deployer-git: v3.0.0 → v4.0.0
• 生成器:
  • hexo-generator-archive: v1.0.0 → v2.0.0
  • hexo-generator-category: v1.0.0 → v2.0.0
  • hexo-generator-feed: v3.0.0 → v4.0.0
  • hexo-generator-index: v2.0.0 → v4.0.0
  • hexo-generator-search: v2.4.3 → v2.4.3 (已是最新)
  • hexo-generator-sitemap: v3.0.1 → v3.0.1 (已是最新)
  • hexo-generator-tag: v1.0.0 → v2.0.0
• Markdown-it 插件:
  • markdown-it-container: v3.0.0 → v4.0.0
  • markdown-it-deflist: v2.1.0 → v3.0.0
  • markdown-it-emoji: v2.0.2 → v3.0.0
  • markdown-it-mark: v3.0.1 → v4.0.0
• 其他工具:
  • workbox-build: v6.5.4 → v7.4.0
  • vanilla-lazyload: v17.8.3 → v19.1.3

升级步骤

1. 备份项目

在进行任何升级之前，请务必备份整个项目目录。

2. 升级依赖

``bash

升级 Hexo 核心

npm install hexo@latest --save

升级核心渲染器

npm install [email protected] [email protected] --save

升级生成器插件

npm install [email protected] [email protected] [email protected] [email protected] [email protected] --save

升级 Markdown-it 插件

npm install [email protected] [email protected] [email protected] [email protected] --save

升级其他工具

npm install [email protected] [email protected] --save

升级部署器

npm install [email protected] --save

移除 npm 主题依赖（使用本地自定义主题）

npm uninstall hexo-theme-butterfly

更新所有依赖并同步 lock 文件

npm install

### 3. 修复兼容性问题
由于 Hexo 8.x 版本对日志系统的改动，需要修复 Butterfly 主题中的脚本文件：

**文件**: `themes/butterfly/scripts/events/init.js`
```javascript
// 修改前
const logger = require('hexo-log')()

// 修改后
const logger = hexo.log

文件: themes/butterfly/scripts/events/welcome.js

// 修改前
const logger = require('hexo-log')()

// 修改后
const logger = hexo.log

4. 测试升级结果

# 清理并生成站点
npx hexo clean && npx hexo generate

# 启动本地服务器测试
npx hexo server

注意事项

1. 兼容性: 某些旧插件可能与新版本 Hexo 不完全兼容，如遇到问题可考虑寻找替代方案。
2. 配置文件: 主题配置文件 _config.butterfly.yml 可能需要根据新版本主题进行调整。
3. 自定义功能: 如果有自定义的脚本或样式，需要测试确保在新版本中正常工作。
4. 性能优化: 新版本通常包含性能改进和安全修复，建议定期更新。
5. 依赖版本验证: 在升级前，建议使用 npm view <package-name> versions --json 验证目标版本是否存在。
6. 主题管理: 已移除 npm 主题依赖，完全使用本地 themes/butterfly/ 目录，这样可以更好地控制自定义修改。

验证升级成功

• 本地服务器正常启动 (http://localhost:4000)
• 所有页面正常显示
• 功能组件（搜索、评论、加密文章等）正常工作
• 构建过程无错误
• 确认 npm list hexo-theme-butterfly 显示为空

故障排除

如果遇到问题：

1. 检查控制台错误信息
2. 查看具体插件的兼容性文档
3. 考虑暂时降级有问题的插件

已知限制

• Gulp v5: 由于依赖冲突，Gulp 保持在 v4.0.2 版本
• 部分插件: 某些插件（如 [email protected]）版本较旧，但仍在工作
• 主题版本: 使用本地自定义主题 v4.3.1，未升级到最新官方版本以保留自定义修改

---

升级完成时间: 2026-02-12
升级人: chengfeng3012