第 1 篇，共 6 篇 · 系列总目录 · 上一篇：无 · 下一篇：导航、首页与文章页配置

前言

这个博客最初也是从一套几乎没有修改的 Hexo + Butterfly 开始的。随着文章和组件逐渐增加，它后来拥有了亮暗主题背景、音乐播放器、分类磁贴、全局搜索、随机封面图池和自定义页脚等功能。

不过，在添加这些功能之前，最重要的仍然是建立一套稳定、容易维护的基础结构。

本系列将从一个空目录开始，逐步完成：

  1. Hexo 博客的创建与运行
  2. Butterfly 主题的安装和基础配置
  3. 首页、文章页、分类、标签与友链页面
  4. 一图流背景和明暗主题美化
  5. 通过 CSS 与 JavaScript 添加自定义组件
  6. 部署、更新日志和长期维护

本文是系列第一篇，只处理安装、配置关系和首次本地预览。完成以后，你会得到一个可以正常写文章、切换主题并继续扩展的 Butterfly 博客。

本文示例基于 Hexo 7.3 与 Butterfly 5.4。主题后续版本可能调整配置名称，请同时参考文章末尾的官方文档。

一、开始之前需要准备什么

Hexo 是一个静态网站生成器。我们用 Markdown 写文章，Hexo 将文章、主题模板和配置组合起来，生成可以部署到 GitHub Pages、Cloudflare Pages 等平台的静态网页。

Butterfly 则是负责页面外观和交互的 Hexo 主题。

整个过程可以简化为：

1
2
3
4
5
6
7
8
9
Markdown 文章
      +
Hexo 站点配置
      +
Butterfly 主题
      ↓
生成静态 HTML、CSS 和 JavaScript
      ↓
部署到网站托管平台

开始前请安装：

  • Node.js
  • Git
  • 一个代码编辑器，例如 Visual Studio Code

打开终端，确认环境可用：

1
2
3
node --version
npm --version
git --version

只要三条命令都能输出版本号，就可以继续。

Node.js 应该选择哪个版本

建议选择 Node.js 官网当前仍受支持的 LTS 版本，不要使用已经停止维护的旧版本。Hexo、主题或插件的报错，有时并不是配置错误，而是 Node.js 版本过旧造成的。

二、创建一个新的 Hexo 博客

1. 安装 Hexo 命令行工具

可以把 Hexo CLI 安装到全局：

1
npm install hexo-cli -g

然后创建博客：

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

如果不希望安装全局命令，也可以使用 npx：

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

hexo init 的目标文件夹最好为空。不要在已经存放重要文件的目录里直接初始化。

2. 认识项目目录

初始化完成后，主要目录如下：

1
2
3
4
5
6
7
my-blog/
├── _config.yml
├── package.json
├── scaffolds/
├── source/
│   └── _posts/
└── themes/

它们分别负责：

路径 作用
_config.yml Hexo 站点级配置
package.json npm 依赖和运行命令
source/_posts Markdown 文章
source 页面、图片和自定义静态资源
scaffolds 新建文章时使用的模板
themes 使用 Git 下载的本地主题目录
public 执行生成命令后产生的网站文件

public 是自动生成目录，不应该在里面直接修改文章或样式。下一次执行 hexo clean 后，其中的手动修改会全部消失。

3. 第一次启动

1
npx hexo server

终端通常会显示：

1
Hexo is running at http://localhost:4000/

在浏览器打开这个地址，就可以看到默认主题。

停止服务时按：

1
Ctrl + C

三、安装 Butterfly

Butterfly 可以通过 npm 或 Git 安装。本文使用 npm，因为依赖关系更加清晰，更新也比较方便。

在 Hexo 根目录执行：

1
2
npm install hexo-theme-butterfly --save
npm install hexo-renderer-pug hexo-renderer-stylus --save

安装完成后，npm 版本的主题通常位于：

1
node_modules/hexo-theme-butterfly/

它不会出现在 themes/butterfly 中，这是正常现象。

启用主题

打开 Hexo 根目录的 _config.yml，找到：

1
theme: landscape

修改为：

1
theme: butterfly

然后重新生成并启动：

1
2
3
npx hexo clean
npx hexo generate
npx hexo server

如果页面已经变成 Butterfly 的卡片式布局，说明主题安装成功。

四、为什么需要 _config.butterfly.yml

Butterfly 自带一份主题默认配置：

1
node_modules/hexo-theme-butterfly/_config.yml

我们当然可以直接修改它，但不应该这样做。执行 npm update 或重新安装依赖时，node_modules 中的修改可能被覆盖。

更安全的方法，是把主题配置复制到 Hexo 根目录，并命名为：

1
_config.butterfly.yml

Windows PowerShell 可以执行：

1
Copy-Item node_modules\hexo-theme-butterfly\_config.yml _config.butterfly.yml

macOS 或 Linux 可以执行：

1
cp node_modules/hexo-theme-butterfly/_config.yml _config.butterfly.yml

此后，个人设置都写在根目录的 _config.butterfly.yml 中。

Hexo 会合并主题默认配置和个人主题配置；遇到相同字段时，根目录 _config.butterfly.yml 的优先级更高。

复制配置之后，不要删除主题包中的原始 _config.yml。它仍然是主题的默认配置来源。

五、三个配置层分别负责什么

初次使用 Hexo 时，最容易混淆的是 _config.yml、_config.butterfly.yml 和文章顶部的 Front Matter。

1. Hexo 的 _config.yml

它负责整个站点的基础数据和生成规则，例如：

1
2
3
4
5
6
7
8
9
10
11
title: 我的博客
subtitle: 记录学习与创造
author: your-name
language: zh-CN
timezone: Asia/Shanghai

url: https://example.com
permalink: :year/:month/:day/:title/

theme: butterfly
per_page: 10

这里通常配置：

  • 网站名称和作者
  • 网站正式地址
  • 文章永久链接格式
  • 每页文章数量
  • 当前使用的主题
  • 分类、标签和归档生成规则
  • 部署目标

2. Butterfly 的 _config.butterfly.yml

它负责主题外观和组件，例如：

  • 导航菜单
  • Logo 和头像
  • 首页背景与文章封面
  • 亮暗主题
  • 侧栏卡片
  • 文章目录
  • 评论与搜索
  • 页面动画
  • 自定义 CSS 和 JavaScript

3. 每篇文章的 Front Matter

Markdown 最上方由 --- 包围的区域用于设置单篇文章：

1
2
3
4
5
6
7
8
9
10
11
12
13
---
title: 我的第一篇文章
date: 2026-07-30 20:00:00
updated: 2026-07-30 20:00:00
categories:
  - Web 开发
tags:
  - Hexo
  - Butterfly
description: 这是显示在首页文章卡片上的简介。
cover: /img/post-covers/example.webp
top_img: /img/banner.webp
---

可以把三者记成：

1
2
3
_config.yml             决定网站怎样生成
_config.butterfly.yml   决定主题怎样显示
Front Matter            决定这一篇文章怎样显示

六、完成第一轮基础配置

Butterfly 的完整配置很长，不需要第一次就把所有选项都打开。我们先完成最容易看到效果的部分。

1. 设置 Logo 和导航栏

在 _config.butterfly.yml 中修改：

1
2
3
4
5
6
7
8
9
10
11
12
13
nav:
  logo: /img/logo.svg
  display_title: true
  display_post_title: true
  fixed: false

menu:
  首页: / || fas fa-home
  文章||fas fa-archive:
    归档: /archives/ || fas fa-archive
    标签: /tags/ || fas fa-tags
    分类: /categories/ || fas fa-folder-open
  友链: /link/ || fas fa-link

菜单格式可以理解为：

1
显示文字: 页面地址 || 图标类名

图片应放在 Hexo 根目录的 source/img 中：

1
source/img/logo.svg

生成网站后，它的访问地址就是：

1
/img/logo.svg

2. 设置头像和社交链接

1
2
3
4
5
6
7
avatar:
  img: /img/avatar.png
  effect: false

social:
  fab fa-github: https://github.com/your-name || GitHub || '#24292e'
  fas fa-envelope: mailto:you@example.com || Email || '#4a7dbe'

社交链接由四部分组成：

1
图标: 地址 || 鼠标提示 || 图标颜色

3. 设置首页背景

1
2
3
4
disable_top_img: false
default_top_img: /img/background.webp
background: /img/background.webp
footer_img: /img/background.webp

建议把背景图片转换为 WebP，以降低文件大小。桌面背景最好准备较高分辨率，同时还要考虑手机竖屏裁切；后续文章会单独介绍桌面端、移动端和暗色主题使用不同背景的方法。

4. 设置首页副标题

1
2
3
4
5
6
7
subtitle:
  enable: true
  effect: true
  source: false
  sub:
    - 吾生也有涯，而知也无涯
    - Life is finite while knowledge is infinite

effect: true 会启用打字机动画。source: false 表示不读取第三方随机句子接口，只显示自己配置的内容。

5. 设置文章卡片布局

1
2
3
4
5
index_layout: 3

index_post_content:
  method: 2
  length: 300

index_layout: 3 表示首页文章封面左右交替。

摘要方式 method: 2 表示：

  1. 文章存在 description 时优先使用；
  2. 没有时从正文自动截取。

6. 设置蓝色主题

1
2
3
4
5
6
7
8
9
10
11
theme_color:
  enable: true
  main: "#3B82F6"
  paginator: "#2563EB"
  button_hover: "#60A5FA"
  text_selection: "#93C5FD"
  link_color: "#2563EB"
  toc_color: "#3B82F6"
  scrollbar_color: "#3B82F6"
  meta_theme_color_light: "#ffffff"
  meta_theme_color_dark: "#0d0d0d"

颜色值建议始终放在引号中，避免 YAML 把 # 后面的内容识别成注释。

7. 启用暗色模式

1
2
3
4
5
6
darkmode:
  enable: true
  button: true
  autoChangeMode: false

display_mode: light

这样网站默认使用亮色模式，同时在右侧工具栏提供切换按钮。

七、创建归档、标签和分类页面

归档通常由 Hexo 自动生成。标签页和分类总览页可以手动创建：

1
2
npx hexo new page tags
npx hexo new page categories

打开 source/tags/index.md：

1
2
3
4
5
---
title: 标签
date: 2026-07-30 20:00:00
type: tags
---

打开 source/categories/index.md：

1
2
3
4
5
---
title: 分类
date: 2026-07-30 20:00:00
type: categories
---

只有文章 Front Matter 中真正填写了分类和标签，它们才会出现在对应页面。

八、创建并检查第一篇文章

执行：

1
npx hexo new post "my-first-post"

Hexo 会在 source/_posts 中创建 Markdown 文件。加入一些内容：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
---
title: 我的第一篇文章
date: 2026-07-30 20:00:00
categories:
  - 随笔
tags:
  - Hexo
description: 这是我的第一篇 Hexo 博客文章。
---

## 你好，Hexo

这是正文内容。

<!-- more -->

这里是展开文章后才能看到的内容。

<!-- more --> 用于指定首页摘要的结束位置。它不是必须的，但能让首页卡片更加可控。

重新启动本地服务器：

1
2
3
npx hexo clean
npx hexo generate
npx hexo server

检查以下内容：

  • 首页是否出现文章
  • 封面和简介是否正确
  • 分类、标签能否点击
  • 导航栏是否跳转正确
  • 亮暗主题能否切换
  • 手机宽度下是否正常排版

九、常用命令与 npm 脚本

Hexo 原生命令如下：

1
2
3
4
npx hexo clean
npx hexo generate
npx hexo server
npx hexo deploy

含义分别是：

命令 作用
clean 删除上一次生成的缓存和 public
generate 生成静态网站
server 启动本地预览
deploy 按部署配置发布网站

也可以在 package.json 中定义更容易记忆的脚本：

1
2
3
4
5
6
7
8
{
  "scripts": {
    "clean": "hexo clean",
    "build": "hexo generate",
    "server": "hexo server",
    "deploy": "hexo generate && hexo deploy"
  }
}

之后就可以使用：

1
2
3
4
npm run clean
npm run build
npm run server
npm run deploy

npm run deploy 并不是另一种部署技术，它只是执行 package.json 中预先定义的一组命令。它还可以在部署前加入检查、生成更新日志等自动操作。

十、常见问题

1. localhost:4000 无法打开

先确认终端中的 Hexo Server 没有退出，并检查 4000 端口是否被其他程序占用。也可以换一个端口：

1
npx hexo server -p 5000

然后访问：

1
http://localhost:5000/

2. 页面显示 Pug 源代码或模板报错

检查渲染器：

1
npm install hexo-renderer-pug hexo-renderer-stylus --save

安装后重新执行：

1
2
npx hexo clean
npx hexo generate

3. 修改配置后没有变化

可能原因包括：

  • YAML 缩进错误
  • 改错了配置文件
  • 本地服务器没有重新启动
  • 浏览器仍在使用缓存
  • 修改了 public，随后又被重新生成覆盖
  • 使用 _config.butterfly.yml 后仍在修改主题包内的配置

可以依次执行：

1
2
3
npx hexo clean
npx hexo generate
npx hexo server

4. YAML 报错

YAML 使用空格表示层级，不要使用 Tab：

1
2
menu:
  首页: /

下面这种写法层级不正确：

1
2
menu:
首页: /

包含冒号、# 或其他特殊字符的文本，最好使用引号包裹。

5. npm 安装速度慢或失败

先检查 Node.js、npm 和网络环境，不要一开始就反复删除整个项目。可以通过下面的命令检查依赖状态：

1
2
npm install
npm ls --depth=0

如果项目已经有 package-lock.json，在其他电脑恢复环境时应一起保留它。

十一、不要直接修改这些位置

为了以后能顺利更新主题，尽量不要直接修改：

1
2
node_modules/hexo-theme-butterfly/
public/

个人文件建议放在：

1
2
3
4
source/css/
source/js/
source/img/
source/_posts/

主题配置放在：

1
_config.butterfly.yml

后续需要添加自定义样式和脚本时，可以使用 Butterfly 的 inject 配置加载，而不是修改主题本体：

1
2
3
4
5
inject:
  head:
    - <link rel="stylesheet" href="/css/custom.css">
  bottom:
    - <script defer src="/js/custom.js"></script>

这也是本系列后续制作背景动画、音乐播放器和分类磁贴时采用的主要方式。

十二、下一步做什么

到这里，一个基础的 Hexo + Butterfly 博客已经搭建完成：

  • Hexo 可以正常生成页面
  • Butterfly 已安装并启用
  • 个人配置与主题包分离
  • 导航、头像、背景和主题色已经可以修改
  • 标签和分类页面已经建立
  • 已经能够创建和预览文章

下一篇将继续介绍 Butterfly 的导航栏、首页文章卡片、文章 Front Matter、封面、侧栏和页脚配置，并结合本站当前配置说明每一项修改会产生什么效果。

参考资料与声明

本文参考 Butterfly 官方文档，并结合本站实际搭建、配置和维护过程重新整理。不同版本的 Hexo、Butterfly 和第三方插件可能存在配置差异，请以对应版本的官方说明为准。

本文部分结构与文字由 AI 协助整理，配置示例由作者结合实际项目进行检查。

第 1 篇，共 6 篇 · 返回系列总目录 · 下一篇：导航、首页与文章页配置