hexo-theme-Butterfly 主题安装与基础配置操作教程

🌟前提条件：

-  ✅ 已部署 Hexo 项目
-  🔗 安装教程参考：Hexo站点搭建 | GitHub部署 | Cloudflare Pages发布 | 保姆级教程

🎨 安装 Butterfly 主题

🔽 下载主题（推荐方式：Git 克隆）

-  国内用户建议使用 Gitee：

1
git clone -b master https://gitee.com/immyw/hexo-theme-butterfly.git themes/butterfly
-  网络环境较好可使用 GitHub：

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

⚙️ 应用主题

-  修改 Hexo 根目录下的 _config.yml：

1
theme: butterfly

📦 安装依赖插件

-  如果未安装 pug 与 stylus 渲染器，请执行：

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

📁 配置建议（可选）

为了减少时间上维护或主题升级引起的混乱，建议使用外部配置文件管理主题配置：

- 在 Hexo 根目录创建文件 _config.butterfly.yml
- 将 themes/butterfly/_config.yml 中所有内容复制到该文件

运行以下命令来快捷操作

1
copy "themes\butterfly\_config.yml" "_config.butterfly.yml"

🌟 子模块配置

  1. 创建 .gitmodules 文件
    运行创建命令：
1
echo. > .gitmodules

编辑 .gitmodules 文件，添加以下内容，确保路径和 URL 正确：

1
2
3
[submodule "themes/butterfly"]
  path = themes/butterfly
  url = https://github.com/jerryc127/hexo-theme-butterfly.git
  1. 添加 .gitmodules 文件到版本控制
1
2
3
git add .gitmodules
git commit -m "Add .gitmodules file"
git push origin main
  1. 初始化和更新子模块
    初始化和更新子模块：
1
2
git submodule init   # 初始化子模块
git submodule update --recursive   # 拉取子模块代码
  1. 检查子模块状态
    确认子模块是否正确同步：
1
git submodule status
  1. 推送到远程仓库
    将子模块变更推送到远程仓库：
1
2
3
git add themes/butterfly
git commit -m "Add butterfly theme as submodule"
git push origin main

🛠️ 基础配置

- Hexo 全局配置文件：**_config.yml** 
    > 官方文档：https://hexo.io/zh-cn/docs/configuration

- Butterfly 主题配置文件：**_config.butterfly.yml**
    > 官方文档：https://butterfly.js.org/

✍️ 文章发布说明

✅ 推荐编辑器
Hexo 默认使用 Markdown 格式撰写文章，推荐使用以下编辑器：

- **VSCode**：功能强大，支持多种语言和插件扩展
- **MarkText**：轻量级、开源、免费（目前仅英文界面）

安装包我已上传至云盘，可自取：云盘传送

🔧 创建与编辑文章

  1. 打开终端，进入 Hexo 项目根目录
  2. 创建文章：
1
hexo new "posts"       # 创建一篇文章 posts.md

文章文件会生成在 /source/_posts/ 目录下

使用 Markdown 编辑器打开 posts.md，编写文章内容

💡 小技巧：可以先在 Word 或 TXT 中撰写内容，再使用 AI（如 DeepSeek）转换为 Markdown 格式，粘贴进 Hexo 文章中。

🚀 发布文章

依次执行以下命令：

1
2
3
4
5
6
7
8
hexo generate        # 生成静态文件
hexo deploy          # 部署至远程仓库

git add .            # 添加所有更改到本地 git

git commit -m "update"   # 描述本次更改

git push origin main     # 推送到远程仓库

等待上传成功后，刷新站点即可看到文章上线。