博客搭建完整教程
基于 Hexo + Butterfly 主题 + GitHub Pages 的完整博客搭建指南
目录
- 环境准备
- Hexo 安装与初始化
- Butterfly 主题安装
- Live2D 看板娘配置
- Giscus 评论系统
- 搜索功能配置
- 自定义样式
- 创建页面和文章
- 部署到 GitHub Pages
- 进阶配置
1. 环境准备
1.1 Node.js 安装
访问 Node.js 官网 下载并安装 LTS 版本。
安装完成后，打开终端验证：
1
2
| node --version
npm --version
|
1.2 Git 安装
访问 Git 官网 下载并安装。
配置 Git 用户信息：
1
2
| git config --global user.name "你的用户名"
git config --global user.email "你的邮箱"
|
2. Hexo 安装与初始化
2.1 安装 Hexo CLI
2.2 初始化博客
1
2
3
4
5
6
7
|
hexo init myblog
cd myblog
npm install
hexo server
|
访问 http://localhost:4000 查看默认博客。
2.3 博客文件夹结构
1
2
3
4
5
6
7
8
9
| myblog/
├── _config.yml # 站点配置文件
├── package.json # 依赖管理
├── scaffolds/ # 文章模板
├── source/ # 源文件目录
│ ├── _drafts/ # 草稿
│ └── _posts/ # 文章
├── themes/ # 主题目录
└── public/ # 生成的静态文件
|
3. Butterfly 主题安装
3.1 下载 Butterfly 主题
1
2
3
4
5
|
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
npm install hexo-renderer-pug hexo-renderer-stylus --save
|
3.2 启用主题
修改根目录下的 _config.yml：
3.3 复制主题配置文件
1
| cp themes/butterfly/_config.yml _config.butterfly.yml
|
3.4 基础配置
编辑 _config.butterfly.yml：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
|
menu:
首页: / || fas fa-home
归档: /archives/ || fas fa-archive
标签: /tags/ || fas fa-tags
分类: /categories/ || fas fa-folder-open
关于: /about/ || fas fa-heart
favicon: /img/favicon.ico
avatar:
img: /img/avatar.jpg
effect: false
subtitle:
enable: true
sub1: 欢迎来到我的博客
sub2: 分享技术与生活
|
4. Live2D 看板娘配置
4.1 安装 Live2D 插件
1
2
| npm install hexo-helper-live2d --save
npm install live2d-widget-model-haru --save
|
4.2 配置 Live2D
在根目录 _config.yml 中添加：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
| live2d:
enable: true
scriptFrom: local
pluginRootPath: live2dw/
pluginJsPath: lib/
pluginModelPath: assets/
tagMode: false
debug: false
model:
use: live2d-widget-model-haru
display:
position: right
width: 150
height: 300
mobile:
show: false
react:
opacity: 0.7
|
4.3 可选模型
1
2
3
4
|
npm install live2d-widget-model-shizuku --save
npm install live2d-widget-model-miku --save
npm install live2d-widget-model-wanko --save
|
5. Giscus 评论系统
5.1 准备工作
- 创建 GitHub 公开仓库用于存储评论
- 安装 Giscus App
- 在仓库设置中启用 Discussions 功能
5.2 获取配置参数
访问 Giscus 官网 获取配置参数。
5.3 配置 Giscus
在 _config.butterfly.yml 中配置：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
| comments:
use: Giscus
text: true
lazyload: true
count: true
card_post_count: true
giscus:
repo: 你的用户名/评论仓库名
repo_id: 你的仓库ID
category_id: 你的分类ID
theme:
light: light
dark: dark
option:
data-lang: zh-CN
data-loading: lazy
crossorigin: anonymous
|
6. 搜索功能配置
6.1 安装搜索插件
1
| npm install hexo-generator-search --save
|
6.2 配置搜索
在根目录 _config.yml 中添加：
1
2
3
4
5
| search:
path: search.xml
field: post
content: true
format: html
|
在 _config.butterfly.yml 中启用：
1
2
3
4
| local_search:
enable: true
preload: false
CDN:
|
7. 自定义样式
7.1 创建自定义 CSS
创建 source/css/custom.css：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
|
.video-container {
position: relative;
padding-bottom: 56.25%;
height: 0;
overflow: hidden;
}
.video-container iframe {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
}
#aside-content .card-widget.card-info {
background: linear-gradient(-45deg, #ee7752, #e73c7e, #23a6d5, #23d5ab);
background-size: 400% 400%;
animation: gradientBG 15s ease infinite;
}
@keyframes gradientBG {
0% { background-position: 0% 50%; }
50% { background-position: 100% 50%; }
100% { background-position: 0% 50%; }
}
.button--animated {
background: linear-gradient(45deg, #667eea 0%, #764ba2 100%);
border: none;
border-radius: 25px;
color: white;
padding: 10px 20px;
text-decoration: none;
display: inline-block;
transition: all 0.3s ease;
box-shadow: 0 4px 15px rgba(102, 126, 234, 0.4);
}
.button--animated:hover {
transform: translateY(-2px);
box-shadow: 0 8px 25px rgba(102, 126, 234, 0.6);
}
|
7.2 引入自定义样式
在 _config.butterfly.yml 中添加：
1
2
3
| inject:
head:
- <link rel="stylesheet" href="/css/custom.css">
|
8. 创建页面和文章
8.1 创建关于页面
编辑 source/about/index.md：
1
2
3
4
5
6
7
8
9
| ---
title: 关于我
date: 2024-01-01 00:00:00
type: about
---
# 关于我
这里是关于页面的内容...
|
8.2 创建标签页面
编辑 source/tags/index.md：
1
2
3
4
5
| ---
title: 标签
date: 2024-01-01 00:00:00
type: tags
---
|
8.3 创建分类页面
1
| hexo new page categories
|
编辑 source/categories/index.md：
1
2
3
4
5
| ---
title: 分类
date: 2024-01-01 00:00:00
type: categories
---
|
8.4 创建新文章
9. 部署到 GitHub Pages
9.1 创建 GitHub 仓库
- 在 GitHub 创建新仓库，命名为
username.github.io
- 仓库设置为 Public
9.2 安装部署插件
1
| npm install hexo-deployer-git --save
|
9.3 配置部署
在根目录 _config.yml 中配置：
1
2
3
4
5
6
7
8
9
|
url: https://username.github.io
root: /
deploy:
type: git
repo: git@github.com:username/username.github.io.git
branch: main
|
9.4 部署博客
1
2
3
4
5
6
7
8
9
|
hexo clean
hexo generate
hexo deploy
hexo clean && hexo g && hexo d
|
10. 进阶配置
10.1 SEO 优化
安装 SEO 插件：
1
2
| npm install hexo-generator-sitemap --save
npm install hexo-generator-baidu-sitemap --save
|
配置 sitemap：
1
2
3
4
5
| sitemap:
path: sitemap.xml
baidusitemap:
path: baidusitemap.xml
|
10.2 图片懒加载
在 _config.butterfly.yml 中启用：
1
2
3
4
5
| lazyload:
enable: true
field: site
placeholder:
blur: false
|
10.3 代码高亮
配置代码块主题：
1
2
3
4
| highlight_theme: mac
highlight_copy: true
highlight_lang: true
highlight_shrink: false
|
10.4 数学公式支持
安装 MathJax：
1
| npm install hexo-filter-mathjax --save
|
配置：
1
2
3
| mathjax:
enable: true
per_page: false
|
11. 移动端优化
11.1 响应式设计
确保主题支持移动端：
1
2
3
| mobile:
scale: 0.8
header_height: 45px
|
11.2 PWA 支持
安装 PWA 插件：
1
| npm install hexo-offline --save
|
12. 常用脚本
创建便捷脚本 scripts/blog.sh：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
| #!/bin/bash
if [ "$1" = "new" ]; then
hexo new "$2"
echo "文章 '$2' 创建成功！"
fi
if [ "$1" = "server" ]; then
hexo clean && hexo g && hexo s
fi
if [ "$1" = "deploy" ]; then
hexo clean && hexo g && hexo d
echo "博客部署完成！"
fi
|
使用方法：
1
2
3
4
5
6
7
8
|
./scripts/blog.sh new "文章标题"
./scripts/blog.sh server
./scripts/blog.sh deploy
|
13. 常见问题解决
13.1 部署失败
检查 SSH 密钥配置：
1
2
| ssh-keygen -t rsa -C "your_email@example.com"
cat ~/.ssh/id_rsa.pub
|
13.2 主题更新
1
2
| cd themes/butterfly
git pull
|
13.3 插件冲突
清理 node_modules：
1
2
| rm -rf node_modules
npm install
|
14. 性能优化
14.1 图片压缩
安装图片压缩插件：
1
| npm install hexo-imagemin --save
|
14.2 CDN 加速
配置 CDN：
1
2
3
| CDN:
internal_provider: local
third_party_provider: cdnjs
|
14.3 缓存优化
启用浏览器缓存：
1
2
3
4
5
6
7
8
9
10
| open_graph:
enable: true
options:
twitter_card: summary_large_image
twitter_image:
twitter_id:
twitter_site:
google_plus:
fb_admins:
fb_app_id:
|
15. 总结
通过本教程，你已经成功搭建了一个功能完整的 Hexo 博客，包括：
- ✅ Hexo 框架安装和配置
- ✅ Butterfly 主题美化
- ✅ Live2D 看板娘
- ✅ Giscus 评论系统
- ✅ 搜索功能
- ✅ 自定义样式
- ✅ GitHub Pages 部署
- ✅ SEO 和性能优化
现在你可以开始写作，分享你的知识和想法了！
16. 相关资源
💡 提示: 定期备份你的博客源码，建议将源码也推送到 GitHub 仓库的 source 分支进行版本管理。
🎉 恭喜: 你的博客搭建完成！现在开始你的写作之旅吧！