Hexo + Butterfly 搭建个人博客全流程攻略

一、环境准备

1. 安装 Node.js

Hexo 基于 Node.js，首先需要安装 Node.js。

去 Node.js 官网下载 LTS 版本并安装。安装完成后验证：

1 2	node -v npm -v

2. 安装 Git

Git 官网下载安装，后续部署和主题克隆都会用到。

1	git --version

二、安装 Hexo

1. 全局安装 Hexo CLI

1	npm install hexo-cli -g

2. 创建博客项目

1
2
3

hexo init my-blog
cd my-blog
npm install

3. 本地预览

1	hexo server

浏览器打开 http://localhost:4000，就能看到默认的 landscape 主题页面。

三、安装 Butterfly 主题

1. 下载主题

推荐使用 Git 克隆到 themes/ 目录：

1	git clone https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

注意： 不要直接通过 npm 安装 hexo-theme-butterfly，Git 克隆的方式更方便后续更新和自定义修改。

2. 安装主题依赖

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

Butterfly 使用 pug 作为模板引擎、stylus 作为 CSS 预处理器，这两个渲染器必须安装。

3. 切换主题

修改根目录下的 _config.yml（不是主题目录里的）：

1	theme: butterfly

4. 安装配套插件（可选）

1 2	npm uninstall hexo-renderer-marked --save npm install hexo-renderer-kramed --save

kramed 对 LaTeX 数学公式的支持更好，如果需要写数学公式建议替换。

5. 重新生成预览

1
2
3

hexo clean
hexo generate
hexo server

再次打开 http://localhost:4000，就能看到 Butterfly 主题生效了。

四、Butterfly 基础配置

主题的配置文件在 themes/butterfly/_config.yml，以下是常用配置项：

网站信息

# 导航菜单
menu:
  Home: / || fas fa-home
  Archives: /archives/ || fas fa-archive
  Tags: /tags/ || fas fa-tags
  Categories: /categories/ || fas fa-folder-open

头像与社交

avatar:
  img: /img/avatar.jpg
  effect: true  # 旋转效果

social:
  GitHub: https://github.com/yourname || fab fa-github
  Email: mailto:you@example.com || fas fa-envelope

代码高亮

在根目录 _config.yml 中配置：

syntax_highlighter: highlight.js
highlight:
  line_number: true
  auto_detect: false
  tab_replace: ''
  wrap: true
  hljs: false

启用搜索

1	npm install hexo-generator-search --save

主题配置中开启：

1 2	local_search: enable: true

五、常用命令

命令	说明
`hexo new "文章标题"`	新建文章
`hexo server`	启动本地服务器
`hexo generate`	生成静态文件
`hexo clean`	清除缓存和生成的静态文件
`hexo deploy`	部署到远程服务器

六、踩坑记录

npm 安装报错 Cannot read properties of null (reading 'matches') — 删除 node_modules 和 package-lock.json，执行 npm cache clean --force，再重新 npm install。
Butterfly 主题不生效 — 确认根目录 _config.yml 中 theme: butterfly，且 hexo-renderer-pug 和 hexo-renderer-stylus 已正确安装。
页面 404 / Cannot GET / — 检查 source/_posts/ 是否有文章，没有文章就没有可渲染的页面。

以上就是从零搭建 Hexo + Butterfly 博客的完整流程，祝你搭建顺利！