导读：用 Hexo + Butterfly 主题搭建博客的完整教程，本文讲本地环境配置、主题安装、插件配置。

系列文章导航

  1. Hexo + Butterfly 博客搭建指南(一)：本地环境配置与运行
  2. Hexo + Butterfly 博客搭建指南(二)：部署到 Vercel
  3. Hexo + Butterfly 博客搭建指南(三)：评论系统与功能扩展
  4. Hexo + Butterfly 博客搭建指南(四)：常见问题汇总

前言

环境准备

安装 Node.js

Hexo 基于 Node.js，所以需要先安装 Node.js（建议 18.x 或更高版本）。

下载地址： https://nodejs.org/

安装完成后，在终端运行：

1
2
node -v
npm -v

如果能看到版本号，说明安装成功。

安装 Hexo CLI

1
npm install -g hexo-cli

初始化博客

创建博客目录

1
2
3
hexo init my-blog
cd my-blog
npm install

这会创建一个基础的 Hexo 博客项目。

本地预览

1
hexo server

打开浏览器访问 http://localhost:4000，就能看到默认的博客页面了。

安装 Butterfly 主题

使用 Git Submodule 安装（推荐）

1
2
git init
git submodule add https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

为什么用 Git Submodule？

  • 方便拉取主题更新 - 主题作者发布新版本时，可以直接 git pull 获取最新代码，无需手动下载替换
  • 保持主题代码独立 - 主题作为子模块单独管理，不会和博客内容混在一起，便于版本控制
  • 不会污染主仓库 - 主题的 commit 历史独立存在，主仓库只记录子模块的引用位置，保持仓库整洁
  • 为 Vercel 部署做准备 - Vercel 需要识别 Git 仓库和子模块，这样部署时才能正确获取主题文件

关于 Vercel 部署的具体配置和注意事项，我会在第二篇详细讲解。

启用主题

修改根目录的 _config.yml，找到 theme 配置项：

1
theme: butterfly

创建主题配置文件

复制主题的默认配置（Windows PowerShell）：

1
Copy-Item themes/butterfly/_config.yml _config.butterfly.yml

重要： 以后所有的主题配置都在 _config.butterfly.yml 中修改，不要直接改 themes/butterfly/_config.yml。

安装必要插件

基础插件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 字数统计
npm install hexo-wordcount --save

# Sitemap 生成
npm install hexo-generator-sitemap --save
npm install hexo-generator-baidu-sitemap --save

# RSS 订阅
npm install hexo-generator-feed --save

# 站内搜索
npm install hexo-generator-searchdb --save

# 图片懒加载
npm install hexo-lazyload-image --save

# 代码压缩
npm install hexo-neat --save

配置主题

基本信息

编辑 _config.butterfly.yml：

1
2
3
4
5
6
7
8
# 网站信息
site_name: AJie's Blog
site_description: 记录 AI 学习与探索之旅
site_author: 阿杰
site_url: https://www.promptnet.cn

# 语言
language: zh-CN

导航菜单

1
2
3
4
5
6
7
menu:
  首页: / || fas fa-home
  归档: /archives/ || fas fa-archive
  标签: /tags/ || fas fa-tags
  分类: /categories/ || fas fa-folder-open
  关于: /about/ || fas fa-heart
  友链: /link/ || fas fa-link

性能优化

1
2
3
4
5
6
7
8
9
10
11
12
# 图片懒加载
lazyload:
  enable: true
  field: site
  placeholder: /img/loading.svg

# DNS 预连接
preconnect:
  enable: true
  host:
    - https://cdn.jsdelivr.net
    - https://cdnjs.cloudflare.com

写第一篇文章

创建新文章

1
hexo new "我的第一篇文章"

这会在 source/_posts/ 目录下创建一个 Markdown 文件。

文章 Front-matter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
---
title: 文章标题
date: 2026-05-15 10:00:00
tags:
  - 标签1
  - 标签2
categories:
  - 分类名
description: 文章描述
top_img: /img/banners/banner-home.jpg
cover: /img/covers/cover1.jpg
---

## 第一个章节

这是我的第一篇博客文章！

### 子章节

更多内容...

生成并预览

1
2
3
4
5
# 生成静态文件
hexo generate

# 开启本地服务器
hexo server

或者使用简写命令：

1
2
hexo g  # 生成
hexo s  # 启动服务器

打开浏览器访问 http://localhost:4000，就能看到你的文章了！

项目结构

1
2
3
4
5
6
7
8
9
10
11
12
my-blog/
├── source/              # 源文件
│   ├── _posts/         # 文章
│   ├── about/          # 关于页面
│   ├── link/           # 友链页面
│   └── img/            # 图片
├── themes/
│   └── butterfly/      # 主题（Git Submodule）
├── _config.yml         # Hexo 配置
├── _config.butterfly.yml  # Butterfly 主题配置
├── package.json        # 依赖配置
└── public/             # 生成的静态文件（Git 忽略）

总结与下一篇预告

本文总结

搭建这个博客的过程中，我遇到了不少问题，但也学到了很多：

  1. Hexo + Butterfly 是个不错的选择 - 功能丰富，社区活跃
  2. 本地开发很方便 - 实时预览，快速迭代
  3. 配置需要细心 - H1 标签、插件兼容性都需要注意
  4. 文档很重要 - 遇到问题先看官方文档和 Issues

下一篇预告

在下一篇文章中，我会介绍：

  • 🚀 如何部署到 Vercel
  • 🌐 自定义域名配置

敬请期待！

如果这篇文章帮到了你，欢迎在评论区留言交流！

参考资料