前言
作为一个正在学习网络安全的技术人，我一直想拥有一个属于自己的技术博客，用来记录学习笔记和踩坑经验。经过一段时间的折腾，终于把博客搭起来了。这篇文章完整记录了从环境准备到部署上线的全过程，希望能帮助到同样想搭建博客的你。
一、环境准备与Hexo初始化
1.1 安装Node.js
Hexo基于Node.js运行，建议安装18.x或更高版本。安装完成后在终端验证版本：

1
2
node -v
npm -v

1.2 安装Git
从Git官网下载安装，用于版本控制、主题拉取以及博客后续部署。
1.3 安装Hexo CLI
全局安装Hexo脚手架工具：

1
npm install -g hexo-cli

1.4 初始化博客项目
在普通文件夹下创建博客目录，规避权限报错问题：

1
2
3
4
mkdir projects && cd projects
hexo init my-blog
cd my-blog
npm install

1.5 本地预览博客
启动本地服务，预览初始博客页面：

1
hexo server

访问 http://localhost:4000，看到Hexo默认博客页面即为初始化成功。
⚠️ 踩坑记录：hexo init 连接失败
执行初始化时遇到报错：Failed to connect to github.com port 443 via 127.0.0.1
报错原因：Git全局代理配置与本地代理软件端口不匹配，导致无法正常拉取GitHub资源。
解决方案：

1
2
3
4
5
6
7
# 方案A：取消全局代理（优先推荐）
git config --global --unset http.proxy
git config --global --unset https.proxy

# 方案B：需保留代理时，配置正确端口
git config --global http.proxy http://127.0.0.1:7890
git config --global https.proxy http://127.0.0.1:7890

经验总结：浏览器可正常访问GitHub，不代表Git网络配置正常，二者独立生效，需单独配置。
二、安装Butterfly主题
Butterfly是Hexo热门现代化主题，内置暗黑模式、TOC目录、代码高亮、图片灯箱等丰富功能，无需大量自定义插件，开箱即用。
2.1 克隆主题源码
在博客根目录执行命令，拉取稳定版主题：

1
2
# GitHub官方源（稳定版）
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

国内GitHub访问卡顿/超时，可使用Gitee镜像源：

1
2
# Gitee镜像源
git clone -b master https://gitee.com/immyw/hexo-theme-butterfly.git themes/butterfly

2.2 安装主题依赖
Butterfly依赖pug、stylus渲染器，必须安装否则页面渲染报错：

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

2.3 启用主题
打开博客根目录 _config.yml，修改主题配置：

1
theme: butterfly

2.4 验证主题生效
清除缓存并重启本地服务：

1
hexo clean && hexo server

页面从默认简约样式变为现代化卡片布局，即主题安装启用成功。
三、主题基础个性化配置
3.1 分离主题配置文件（关键）
禁止直接修改themes/butterfly/_config.yml，主题升级会清空自定义配置。
在根目录生成独立主题配置文件，永久保留自定义配置：

1
cp themes/butterfly/_config.yml _config.butterfly.yml

后续所有主题美化、功能开关均修改 _config.butterfly.yml 文件。
3.2 站点基础信息配置
修改根目录 _config.yml，配置网站核心信息：

1
2
3
4
5
6
7
title: SnowSword
subtitle: '记录网络安全学习之路'
description: '网络安全学习笔记与技术分享'
author: Snow
language: zh-CN
timezone: 'Asia/Shanghai'
url: https://user-lzy.github.io

3.3 导航栏菜单配置
修改 _config.butterfly.yml，自定义顶部导航及图标：

1
2
3
4
5
6
menu:
  首页: / || fa-solid fa-house
  归档: /archives/ || fa-solid fa-archive
  分类: /categories/ || fa-solid fa-folder
  标签: /tags/ || fa-solid fa-tags
  关于: /about/ || fa-solid fa-user

3.4 首页文章摘要规则
配置首页文章展示逻辑，优化阅读体验：

1
2
3
index_post_content:
  method: 2          # 优先读取文章description，无则自动截取正文
  length: 500        # 摘要最大字数

3.5 创建必备独立页面
终端执行命令，批量生成分类、标签、关于页面：

1
2
3
hexo new page categories
hexo new page tags
hexo new page about

依次修改对应页面index.md 配置：
source/categories/index.md

1
2
3
4
5
---
title: 分类
type: "categories"
comments: false
---

source/tags/index.md

1
2
3
4
5
---
title: 标签
type: "tags"
comments: false
---

source/about/index.md

1
2
3
4
5
6
7
---
title: 关于我
type: "about"
comments: false
---

欢迎来到我的技术博客！这里主要记录我在网络安全学习中的笔记与踩坑经验。

3.6 头像配置及避坑指南
将头像图片放入 source/images/ 目录，修改 _config.butterfly.yml：

1
2
3
4
5
6
7
8
9
10
11
12
# 侧边栏头像配置
avatar:
  img: /images/14.jpg
  effect: false

# 关于页面信息配置
about:
  enable: true
  avatar: /images/14.jpg
  name: "Snow"
  description: "程序员一枚，正在学习网络安全"
  top_img: /images/14.jpg

避坑提示：头像显示默认占位图，大概率是图片路径错误或未执行 hexo clean 清除缓存。
四、GitHub Pages 部署上线

2026-11-05 补注：下面这一节记录的是当时的搭建过程，保留原文不做修改。该 GitHub 仓库现已不可访问（返回 404），本站已迁移到 Cloudflare Pages；如果照着这一节配置，hexo deploy 会失败。

4.1 创建专属GitHub仓库
登录GitHub，新建公开仓库，仓库名必须严格遵循格式：用户名.github.io（与自己GitHub用户名完全一致），否则无法正常访问。
4.2 安装部署插件
安装Hexo Git部署工具，实现一键部署：

1
npm install hexo-deployer-git --save

4.3 配置部署参数
修改根目录 _config.yml 部署配置：

1
2
3
4
deploy:
  type: 'git'
  repo: https://github.com/user-lzy/user-lzy.github.io.git
  branch: main

4.4 一键部署上线
依次执行清理、生成、部署命令：

1
2
3
hexo clean    # 清除旧缓存文件
hexo generate # 生成静态网站文件
hexo deploy   # 部署到GitHub Pages

部署成功后，访问 https://user-lzy.github.io 即可成功访问个人博客。
五、博客后续优化方向
基础搭建完成后，可按需进行功能优化，提升博客体验：
优化方向 功能说明
站内搜索 安装 hexo-generator-search 实现本地全文搜索
评论系统 接入Giscus、Twikoo等轻量化评论插件
站点统计 开启内置不蒜子统计，展示访客、浏览量数据
暗黑模式 Butterfly原生支持，可直接在配置文件开启切换功能
代码高亮美化 切换主题内置代码高亮配色，适配编程阅读场景
写在最后
搭建个人技术博客门槛并不高，核心在于耐心配置、解决报错。Hexo+Butterfly+GitHub Pages的组合，零成本、高颜值、易维护，非常适合技术新人记录学习历程。
后续我会持续更新网络安全学习笔记，完善博客功能。

相关项目与联系

项目SnowSword —— Windows 10/11 x64 内核分析与 Anti-Rootkit 工具，源码与发布包在 Gitee。

技术合作Windows 内核 / 驱动开发 / 逆向分析 / 兼容性开发，范围与边界见 技术合作。

联系2160752730@qq.com · QQ 2160752730 · 微信 lst_3258110