就在刚刚，我成功搭建了属于自己的个人博客，使用的是 Hexo + Butterfly 主题。这个过程并不算顺利，但正因为踩了很多坑，也让我对 Hexo 博客系统、本地构建以及 GitHub Pages 的部署流程有了更深入的理解。下面记录的是从零开始搭建博客的全过程，以及过程中遇到的各种问题与解决思路。
一、准备工作
我选择在本地 D 盘创建博客项目文件夹，路径如下：
D:\BlogProjects
在 Windows 系统中，命令行默认位于 C 盘，因此在执行 Hexo 相关命令前，必须先手动切换盘符，否则所有操作都会在错误路径下执行。正确的步骤是：
D:
cd D:\BlogProjects
在安装 Hexo 之前，需要确保已经正确安装 Node.js 和 npm，并且版本能够正常使用。
二、初始化 Hexo
在一个空目录中执行以下命令：
hexo init .
npm install
Hexo 会自动生成基础目录结构，包括配置文件、文章目录、主题目录等。如果当前目录不为空，hexo init 会直接报错，因此需要提前清空文件夹，或将原有内容备份。
三、安装 Butterfly 主题
进入 themes 目录：
cd themes
克隆 Butterfly 主题仓库：
git clone https://github.com/jerryc127/hexo-theme-butterfly.git butterfly
返回博客根目录，修改 _config.yml，将主题设置为：
theme: butterfly
随后安装主题依赖：
npm install hexo-renderer-pug hexo-renderer-sass –save
在后续实践中发现，hexo-butterfly 插件并不是必须安装的，否则可能引发插件加载错误。
四、新建第一篇文章
使用 Hexo 提供的命令创建文章：
hexo new “我学会了如何搭建个人博客”
Hexo 会在以下路径生成 Markdown 文件：
D:\BlogProjects\source_posts\我学会了如何搭建个人博客.md
五、编辑文章内容
打开生成的 Markdown 文件，开始编写内容，主要包括：
- 博客搭建的整体流程
- Hexo 的基本使用方式
- 主题配置与本地预览
- 实际遇到的问题和解决过程
六、本地生成与预览
在博客根目录执行以下命令：
hexo clean
hexo generate
hexo server
随后在浏览器中访问：
如果项目配置了 root（例如 /Zhu-OKOL/），则访问地址会变为：
http://localhost:4000/Zhu-OKOL/
此时可以在本地完整预览博客的样式和内容。
七、部署到 GitHub Pages
为了让博客可以在公网访问，需要将生成的静态文件部署到 GitHub Pages。
首先安装部署插件：
npm install hexo-deployer-git –save
然后在 _config.yml 中配置部署信息：
deploy:
type: git
repo: https://github.com/用户名/仓库名.git
branch: main
对于项目页形式的 GitHub Pages，还需要额外配置：
url: https://username.github.io
root: /仓库名/
完成配置后，执行：
hexo clean
hexo generate
hexo deploy
部署完成后，即可通过：
https://username.github.io/仓库名/
访问博客。
八、后续更新博客的正确流程
以后每次更新博客，只需要：
- 编写或修改 source/_posts 下的 Markdown 文件
- 在博客根目录执行：
hexo clean
hexo generate
hexo deploy
本地电脑只负责生成和上传，网页本身会由 GitHub Pages 自动托管，不需要电脑一直开着。
九、自动部署脚本（deploy.bat）
为了减少重复输入命令的麻烦，可以在博客根目录创建 deploy.bat 文件，内容如下：
@echo off
echo === Hexo Deploy Start ===
hexo clean
hexo generate
hexo deploy
echo === Hexo Deploy Finished ===
pause
以后只需要双击该文件，就可以一键完成清理、生成和部署。
搭建个人博客过程中遇到的挫折整理
一、Hexo 主题插件加载失败（EISDIR 报错）
在执行 hexo clean、hexo generate 或 hexo deploy 时，控制台频繁出现：
ERROR Plugin load failed: hexo-butterfly
Error: EISDIR: illegal operation on a directory, read
这个错误并不会中断生成流程，但会在每一步操作前反复出现，严重影响使用体验。最终发现原因是误安装了 hexo-butterfly 插件，而 Butterfly 实际上是主题而非标准 Hexo 插件。卸载该插件后问题彻底消失。
二、跨盘符操作不熟悉
最初在 C 盘打开命令行，却在 D 盘存放博客项目，忘记先输入 D:，导致多次在错误目录下执行 Hexo 命令，引发路径相关错误。
三、版本兼容与依赖问题
Node.js、Hexo 以及主题依赖之间存在版本兼容问题，一些报错信息并不直观，只能通过不断尝试和查阅文档解决。
四、文章显示为“无标题”
创建文章后页面显示“无标题”，最终确认是 Markdown 文件 front-matter 格式不规范，或者主题未正确读取标题字段。
五、默认作者信息未修改
Hexo 默认作者名为 John Doe，头像为默认图片，需要手动修改 _config.yml 才能显示个人信息。
六、本地正常但 GitHub Pages 显示异常
本地 hexo server 显示完全正常，但部署后 CSS 和 JS 丢失，所有链接 404。根本原因是未配置 root，导致资源路径与项目页地址不匹配。
七、GitHub Pages 初次部署失败
首次部署时 Git 提示未设置用户信息，必须手动配置：
git config –global user.name
git config –global user.email
否则无法完成推送。
八、页面部署成功但无任何美化
即使 Pages 显示部署成功，页面依然是纯文本样式。需要修正 root 配置并重新 clean、generate、deploy 才能解决。
九、License 选择的困惑
创建仓库时不清楚 MIT、CC 等许可证的区别，虽然可以后期修改，但仍需要额外学习相关概念。
十、LF / CRLF 警告干扰判断
部署过程中出现大量换行符警告，虽然不影响使用，但在初期容易被误认为是严重错误。
十一、deploy.bat 黑框一闪而过
最初双击 deploy.bat 后窗口瞬间关闭，无法看到报错信息。通过添加 pause 才能正常观察执行过程。
十二、本地 server 地址变化导致误判
在配置 root 后，本地 server 地址变为 /Zhu-OKOL/，如果仍访问根路径，会误以为博客无法启动。
心得体会
这次博客搭建过程让我深刻体会到，技术实践中最耗费时间的并不是“写代码”，而是理解工具的工作方式并解决各种环境与配置问题。从 Hexo 初始化到主题安装，再到 GitHub Pages 部署，每一步都可能因为一个细节而出错。
通过不断排查问题，我逐渐理解了 Hexo 的生成逻辑、主题与插件的区别、本地路径与线上路径的关系，也掌握了使用 Git 管理和部署静态网站的完整流程。虽然过程曲折，但每一次问题被解决之后，都会带来明显的成长和成就感。
最终，这个博客不仅是一个展示平台，更是一段完整的学习记录。它让我意识到，技术能力正是在一次次踩坑、修复和总结中慢慢积累起来的。
更新说明（2026-07）
博客工程现已整合进 Obsidian 库（Zhu-OKOL-vault/Blog）。笔记写好后，在 frontmatter 中加上 published: true，运行 Blog 目录下的“发布到博客.bat”即可一键发布，不再需要手动改格式和图片路径。
