📚 文档目录

🚀 butterfly主题(一)安装部署 - 📌 butterfly主题(二)基本设置 - 🌈 butterfly主题(三)美化

butterfly 是 Hexo 静态网站框架的一个主题，可扩展性较强，适合展示类博客或者网站。

环境

安装

安装 Hexo

  1. Windows 首次安装需启用 windows shell 外部脚本权限，以管理员权限执行执行以下命令，Y 回车确认
1
Set-ExecutionPolicy -ExecutionPolicy Bypass
  1. npm更换国内镜像源
1
npm config set registry https://registry.npmmirror.com/
  1. 安装 hexo 初始化脚本
1
npm install -g hexo-cli
  1. 创建并进入 hexo 目录，作为博客目录
1
mkdir hexo && cd hexo
  1. 初始化(安装 Hexo)
1
hexo init
项目初始结构（版本不同可能有细微差异）
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
.
├── .github
| 	└── dependabot.yml  # 依赖更新脚本，会创建一个新分支存放最新依赖，建议删除
├── node_modules # 依赖
├── scaffolds # 模板，可在这里设置 Front Matter
| 	├── draft.md  # 草稿模板
| 	├── page.md # 页面模板
|	  └── post.md # 文章模板
├── source # 存放文章、页面
|	  └── _posts  # 文章
├── themes  # 主题文件目录
├── _config.landscape.yml # 默认主题配置，安装完新主题后可删除
├── _config.yml # 站点配置文件
├── .gitignore  # git忽略文件，用来指定哪些文件或者目录不被提交
├── package.json  # 包管理配置文件，记录项目信息和依赖名称及版本
└── package-lock.json # 存储每个安装的依赖是哪个版本

安装 butterfly

  1. 下载主题
1
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
  1. 删除themes\butterfly\.git、themes\butterfly\.github目录
1
Remove-Item -LiteralPath "themes\butterfly\.git", "themes\butterfly\.github" -Recurse -Force
  1. 安装 pug 以及 stylus 的渲染器（不安装主题无法显示）
1
npm install hexo-renderer-pug hexo-renderer-stylus --save
  1. 应用主題，修改 hexo 配置文件_config.yml，搜索theme:字段，修改默认主题为butterfly
1
theme: butterfly

常用命令

Hexo基本命令 作用
hexo init 一键安装Hexo
hexo s 本地运行博客，默认端口4000
hexo clean 清除静态资源
hexo g 编译为HTML代码，默认目录public
hexo n title 创建一篇新的文章，文章标题是 title

内容创建

Front Matter

文章和页面的相关参数设置

页面 Front Matter

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
---
title:  # 【必需】页面标题
type: # 【必需】标签、分类和友情链接三个页面需要配置
top_img:  # 【可选】页面顶部图片
toc: # 【可选】侧边栏目录
comments: # 【可选】显示页面评论模块（默认 true）
aside:  # 【可选】显示侧边栏（默认 true）

date: # 【可选】页面创建日期
updated:  # 【可选】页面更新日期
description:  # 【可选】页面描述
keywords: # 【可选】页面关键词
mathjax:  # 【可选】显示mathjax（当设置mathjax的per_page： false时，才需要配置，默认 false）
katex:  # 【可选】显示katex（当设置katex的per_page： false时，才需要配置，默认 false）

aplayer:  # 【可选】在需要的页面加载aplayer的js和css
highlight_shrink: # 【可选】配置代码框是否展开（true/false）（默认为设置中highlight_shrink的配置）
---

文章 Front Matter

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
---
title: 笔记 # 【必需】文章标题
date: 2022-01-12 11:51:53 # 【必需】文章创建日期
categories: 前端 # 【必需】文章分类
tags: CSS # 【必需】文章标签
top_img:  # 【可选】文章顶部图片
cover:  # 【可选】文章封面（如果没有设置top_img，文章页顶部将显示缩略图，可设为false/图片地址/留空）
sticky: 1 # 文章置顶，数值越大，优先级越大

aside:  # 【可选】显示侧边栏 （默认 true）
comments: # 【可选】显示文章评论模块（默认 true）

updated:  # 【可选】文章更新日期
keywords: # 【可选】文章关键词
description:  # 【可选】文章描述，设置后优先出现在文章预览界面

toc:  # 【可选】显示文章TOC（默认为设置中toc的enable配置）
toc_number: # 【可选】显示toc_number（默认为设置中toc的number配置）
toc_style_simple: # 【可选】显示 toc 简洁模式

copyright:  # 【可选】显示文章版权模块（默认为设置中post_copyright的enable配置）
copyright_author: # 【可选】文章版权模块的文章作者
copyright_author_href:  # 【可选】文章版权模块的链接文章作者
copyright_url:  # 【可选】文章版权模块的链接文章链接
copyright_info: # 【可选】文章版权模块的文字版权声明

mathjax:  # 【可选】显示mathjax（当设置mathjax的per_page： false时，才需要配置，默认 false）
katex:  # 【可选】显示katex（当设置katex的per_page： false时，才需要配置，默认 false）
aplayer:  # 【可选】在需要的页面加载aplayer的js和css
highlight_shrink: # 【可选】配置代码框是否展开（true/false）（默认为设置中highlight_shrink的配置）
---

文章多分类写法

1
2
3
categories: 
  - 笔记
  - linux

文章子分类写法

1
2
3
categories: 
  - [笔记,linux]
  - [搭建]

linux是笔记的一个子分类，搭建是单独的一个分类

创建页面

分类页面

1
hexo new page categories

创建完成后在 Front Matter 添加

1
2
3
4
type: "categories"
top_img: false
aside: false
comments: false

标签页面

1
hexo new page tags

创建完成后在 Front Matter 添加

1
2
3
4
type: "tags"
top_img: false
aside: false
comments: false

关于页面

1
hexo new page about

创建完成后在 Front Matter 添加

1
2
3
4
type: "about"
top_img: false
aside: false
comments: false

友链页面

1
hexo new page link

创建完成后在 Front Matter 添加

1
2
3
type: "link"
top_img: false
aside: false

在source/_data目录中（如果沒有_data文件夹，请自行创建），创建一个文件link.yml，编辑你的友链

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
- class_name: 友情链接
  class_desc: 那些人，那些事
  link_list:
    - name: Hexo
      link: https://hexo.io/zh-tw/
      avatar: https://d33wubrfki0l68.cloudfront.net/6657ba50e702d84afb32fe846bed54fba1a77add/827ae/logo.svg
      descr: 快速、简单且强大的博客框架

- class_name: 网站
  class_desc: 值得推荐的网站
  link_list:
    - name: Youtube
      link: https://www.youtube.com/
      avatar: https://i.loli.net/2020/05/14/9ZkGg8v3azHJfM1.png
      descr: 视频网站
    - name: Twitter
      link: https://twitter.com/
      avatar: https://i.loli.net/2020/05/14/5VyHPQqR6LWF39a.png
      descr: 社交分享平台

说说页面

1
hexo new page shuoshuo

创建完成后在 Front Matter 添加

1
2
3
type: "shuoshuo"
top_img: false
aside: false

数据来源

在 Hexo 根目录中的source/_data（如果没有 _data 文件夹，请自行创建），创建一个文件 shuoshuo.yml

author和avatar可省略，会自动去获取配置文件中的author和avatar
如果需要开啓评论，必须配置key，否则不会显示评论按钮

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
- author: Butterfly
  avatar: https://butterfly.js.org/img/avatar.png
  date: 2024-06-21 23:33:26
  key: key-1
  content: |
    This is a sample content for **Author 1**.
    ![Sample Image](https://via.placeholder.com/150)
  tags:
    - tags1
    - tags2
- author: Butterfly
  avatar: https://butterfly.js.org/img/avatar.png
  date: 2024-06-20 23:33:26
  key: key-2
  content: |
    This is a sample content for **Author 2**.
    ![Sample Image](https://via.placeholder.com/150)
  tags:
    - tag2
    - tag3

- author: Butterfly
  avatar: https://butterfly.js.org/img/avatar.png
  date: 2024-06-19 23:33:26
  key: key-3
  content: |
    This is a sample content for **Author 3**.
| 参数 | 解释 | | ---- | ---- | | author | 【可选】作者名称 | | avatar | 【可选】作者头像 | | date | 【必需】日期 | | content | 【必需】内容（ Markdown 格式或者 Html 格式） | | key | 【可选】评论的唯一标识, 开启评论必须配置 | | tag | 【可选】标签 |

注意： 选择远程加载后，本地生成的方法会无效。
远程拉取只支持json

在说说页面 Markdown 里的 front-matter 添加远程链接 
1
shuoshuo_url: xxxxx
Json 的格式：

author和avatar可省略，会自动去获取配置文件中的author和avatar

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
[
  {
    "author": "Butterfly",
    "avatar": "https://butterfly.js.org/img/avatar.png",
    "date": "2024-06-21 23:33:26",
    "content": "This is a sample content for **Author 1**.",
    "key": "key-1",
    "tags": ["tags1", "tags2"]
  },
  {
    "author": "Butterfly",
    "avatar": "https://butterfly.js.org/img/avatar.png",
    "date": "2024-06-20 23:33:26",
    "content": "This is a sample content for **Author 2**.",
    "key": "key-2",
    "tags": ["tag2", "tag3"]
  },
  {
    "author": "Butterfly",
    "avatar": "https://butterfly.js.org/img/avatar.png",
    "date": "2024-06-19 23:33:26",
    "content": "This is a sample content for **Author 3**."
  }
]
| 参数 | 解释 | | ---- | ---- | | author | 【可选】作者名称 | | avatar | 【可选】作者头像 | | date | 【必需】日期 | | content | 【必需】内容（ Markdown 格式或者 Html 格式） | | key | 【可选】评论的唯一标识, 开启评论必须配置 | | tag | 【可选】标签 |

创建文章

创建新文章

1
hexo new 新文章

创建后会在source/_post文件夹生成一个新文章.md文件，内容如下

1
2
3
4
5
---
title: 新文章
date: 2022-04-10 07:31:09
tags:
---

升级

在 hexo-theme-butterfly/releases 查看新版的更新内容，根据实际情况更新你的配置内容。

部署(免备案)

免备案不会暴露自己的隐私(姓名住址等)，但同时也无法使用国内大部分云服务，只能将博客托管在国外服务器，延迟较高还有被墙的风险

Gitlab代码托管

Github虽然是世界上最大的代码托管平台，但并不适合在中国大陆使用，退而求其次选择了国际版Gitlab，Gitee作为备用

1. 全局身份信息配置

1
2
git config --global user.name '你的名字'
git config --global user.email '你的邮箱'

2. SSH 协议配置
用于连接本地和远程仓库，推荐使用 ssh 协议推拉代码，无需重复输入账号密码，详细教程 | Gitee

1
2
3
4
5
6
7
8
9
10
11
12
# 生成公钥和私钥 (按回车 3 下)
ssh-keygen -t ed25519 -C "SSH Key"

# 查看生成的 SSH 公钥和私钥
ls ~/.ssh/

# 读取公钥文件 ~/.ssh/id_ed25519.pub，将公钥添加到 gitlab、gitee
cat ~/.ssh/id_ed25519.pub

# 验证是否成功
ssh -T git@gitlab.com
ssh -T git@gitee.com

3. 初始化本地仓库

1
2
# 初始化仓库并指定分支名为 main
git init -b main

4. 建立本地仓库与远程仓库的连接

1
2
3
4
5
6
7
8
# 设置默认远程仓库为 origin
git push --set-upstream origin main

# 给 origin 添加 Gitlab仓库
git remote add origin git@gitlab.com:xiaoxiudog/hexo.git

# 给 origin 追加 Gitee仓库，实现双仓库
git remote set-url --add origin git@gitee.com:xdogtop/hexo.git

5. 新建shell脚本push.ps1，写入以下命令，执行./push.ps1即可一键推送代码到两个仓库

1
2
3
4
5
6
7
8
# 将项目所有文件都添加到仓库
git add .

# 备注提交时间
git commit -m "$(date)"

# 推送代码
git push

Vercel网页托管

Vercel 可导入Gitlab项目代码自动编译出网站源码并提供网页托管服务，每月100G免费流量，中国大陆平均访问延迟80ms，免备案还有免费HTTPS证书。

国际阿里云OSS图床

Vercel虽然延迟不高，但带宽较小，加载大一点的图片就很慢了，建议用 国际阿里云OSS + PicGo 自建图床，5G免费标准型存储（本地冗余）+ 每月100G免费流量，详细定价，目前日本东京节点还行，免备案但需要非86手机号和VISA信用卡才能注册。

一些免费公共图床(不推荐)：

备用方案(Vercel和谐后)

之前Vercel服务器被墙，导致博客无法访问，备用方案是把博客直接部署到国际阿里云OSS

Gitlab CI:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
stages:
  - setup_ossutil  # 定义阶段

# 定义安全变量，以便 GitLab CI/CD 使用你的阿里云密钥
variables:
  ACCESS_KEY_ID: $ACCESS_KEY_ID
  ACCESS_KEY_SECRET: $ACCESS_KEY_SECRET
  ENDPOINT: "oss-cn-hongkong.aliyuncs.com"

build_job:  # 定义作业
  stage: setup_ossutil  # 作业所属阶段
  image: node:20-alpine  # 运行作业的环境
  before_script:
    - apt-get update && apt-get install -y wget
    - wget https://gosspublic.alicdn.com/ossutil/1.7.6/ossutil64 -O /usr/local/bin/ossutil
    - chmod 755 /usr/local/bin/ossutil
  script:
    - npm install
    - npm run build
    - ossutil config -e $ENDPOINT -i $ACCESS_KEY_ID -k $ACCESS_KEY_SECRET
    - ossutil cp -rf public oss://xdog/

HTTP跳转HTTPS方法：
阿里云OSS没有HTTP自动跳转HTTPS设置项，只有开启阿里云的CDN后才会自动启用HTTP跳转HTTPS，不过我们可以通过JS实现无感跳转。

修改themes\butterfly\layout\includes\head.pug，在最顶端加上下面这段跳转代码即可

1
2
3
4
5
6
<script>
let currentUrl = window.location.href;
if (!currentUrl.startsWith("http://localhost") && !currentUrl.startsWith("https://xdog.top")) {
  window.location.replace("https://xdog.top");
}
</script>

部署(备案)

这里主要是针对域名的ICP备案，域名备案后任何人都能在 工信部 查到你的姓名，如果做了 公安备案 你的所在城市也会暴露，备案后才能正常使用国内云服务厂商的服务。
个人只能在 阿里云ICP备案、腾讯云ICP备案这种云服务厂商备案，需要长期租用这些厂商的服务器才能不掉备案，只搭建博客是不划算的。

依然推荐Gitlab代码托管+Vercel网页托管，方法同上，不同的是备案后可以使用国内CDN对博客进行加速

CDN

  • 又拍云 加入又拍云联盟后可享每月15G免费流量，10G免费储存空间，免费HTTPS证书自动续签，响应延迟平均30ms
  • 多吉云 每月20G免费流量、200万次HTTPS请求，但是储存空间付费(0.003元/GB/日)，不过一年也就1块钱，国内节点，响应延迟平均10ms，详情
  • 缤纷云 每月30G免费流量(国内)，国内节点，响应延迟平均30ms，详情
  • SCDN 免费线路无限流量，付费的也非常便宜，海外 CDN 免实名备案，内地 CDN 要求实名
  • FreeCDN 免费线路无限流量，付费的也非常便宜，海外 CDN 免实名备案，内地 CDN 要求实名