完整的项目重建经验总结

项目重建完整经验总结

这篇文章记录了如何从零开始使用 Hexo + Butterfly 主题重建个人博客站点的完整过程，包括所遇到的问题和解决方案。

第一阶段：需求分析与规划

确定目标

保留原个人身份信息（用户名、描述等）
参考已有的站点风格和布局
保持内容的连贯性
提升站点的整体性能

技术选型

静态站点生成器: Hexo 7.3.0（Node.js 18 兼容）
主题: Butterfly 5.5.4（功能完整，定制性强）
渲染器: Pug + Stylus（Butterfly 依赖）
部署: 静态文件到 /var/www/html

资源获取

克隆参考项目 (handsomelky/handsomelky.github.io)
提取关键 CSS 文件（ref-index.css, ref-equipment.css）
分析页面结构和交互设计

第二阶段：环境搭建与初始化

环境检查

# 检查 Node.js 版本
node --version  # v18.19.1

# 安装 Hexo
npm install -g hexo-cli

# 初始化项目
hexo init blog-rebuild
cd blog-rebuild
npm install

安装主题和依赖

# 安装 Butterfly 主题
git clone https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

# 安装必需渲染器
npm install hexo-renderer-pug hexo-renderer-stylus

# 安装搜索和评论依赖
npm install hexo-generator-search

第三阶段：配置与定制

基础配置

在 _config.yml 中设置：

title: Funtt's Lab
author: Funtt
description: 安全研究与生活记录
language: zh-CN
timezone: Asia/Shanghai

主题配置

复制 themes/butterfly/_config.yml 到项目根目录作为 _config.butterfly.yml，进行定制：

# 导航菜单
menu:
  首页: /
  文章: /archives
  标签: /tags
  分类: /categories
  关于: /about
  友链: /link
  音乐: /music

# 社交媒体
social:
  fab fa-github: https://github.com/Funtt

# 代码高亮
highlight:
  enable: true
  line_number: true

遇到的第一个问题：Stylus @extend 兼容性

问题: Butterfly 主题的 post.styl 使用 @extend .fontawesomeIcon，在 Node 18 上编译失败。

错误信息:

1	Error: Undefined variable: ".fontawesomeIcon"

根本原因: Font Awesome 6 配置变更，.fontawesomeIcon 类不再定义。

解决方案: 修改 themes/butterfly/source/css/_layout/post.styl，用基础字体替代：

.post-meta-code
  font-family: 'Font Awesome 6 Free'
  font-weight: 400
  content: attr(data-char)
  // 不使用 @extend，直接定义属性

第四阶段：样式与交互优化

CSS 资源整合

创建 source/css/optimize.css 统一管理自定义样式：

/* 卡片样式优化 */
.post-preview {
  border-radius: 12px;
  box-shadow: 0 2px 8px rgba(0,0,0,0.08);
  transition: all 0.3s ease;
}

.post-preview:hover {
  box-shadow: 0 8px 16px rgba(0,0,0,0.12);
}

/* 文章摘要显示限制 */
.post-preview .info-2 {
  display: none !important;
}

/* 分页样式 */
.pagination .page-number.current {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

在 _config.butterfly.yml 中注入

inject:
  head:
    - <link rel="stylesheet" href="/css/optimize.css">
  bottom:
    - <script src="/js/live2d-init.js"></script>

第五阶段：功能模块实现

Live2D 交互式看板娘

创建 source/js/live2d-init.js：

window.Live2DInitPlugin = {
    // 初始化配置
    el: '#live2d-widget',
    model: '/live2d/shizuku/shizuku.model.json',
    messages: [
        '欢迎来到 Funtt\'s Lab!',
        '点击可以尝试更多对话~',
        '继续阅读，发现有趣的内容!'
    ],
    // 事件处理
    onMouseEnter: function() {
        this.showMessage('你好！');
    },
    onMessageClick: function() {
        this.cycleMessage();
    }
};

动态标题效果

集成 FunnyTitle.js：

const titles = [
    '( ´▽｀)ノ 欢迎回来~',
    '(´・ω・`) 在忙什么呢',
    '(´；ω；) 别走啊~'
];
// 根据焦点变化显示标题

第六阶段：测试与验证

构建和本地预览

# 清理旧的构建
hexo clean

# 生成静态文件
hexo generate

# 启动本地服务器
hexo server

# 访问 http://localhost:4000 预览

检查清单

页面加载速度
样式和布局是否正确
响应式设计（移动端）
图片加载
JavaScript 功能
SEO 元数据

遇到的第二个问题：样式冲突

问题: 某些参考 CSS 与 Butterfly 原生样式冲突，导致页面布局混乱。

解决方案: 使用 CSS 层叠和特异性优化：

/* 在 optimize.css 中明确覆盖 */
.post-card .info-2 {
  display: none !important;  /* !important 确保优先级 */
}

第七阶段：部署与维护

部署流程

# 生成输出
hexo clean && hexo generate

# 同步到 Web 根目录
rsync -av --delete public/ /var/www/html/

定期维护任务

更新依赖包：npm update
备份重要文件和配置
监控页面性能指标
定期发布新文章

第八阶段：工作流优化

快速发布脚本

创建 deploy.sh：

#!/bin/bash
hexo clean
hexo generate
rsync -av --delete public/ /var/www/html/
echo "部署完成！"

文章模板

在 archetypes/default.md 定义：

---
title: {{ title }}
date: {{ date }}
tags: []
categories: []
---

正文内容...