理想中的博客：

  • 全程免费/极少收费项目
  • 美观
  • 写文章和推送操作简单

理想中的操作过程：

  1. 使用电脑或者手机打开后台管理
  2. 编写文章
  3. 将文章发布到博客

实际上，如果你只是简单地使用 hexo +一些主题，并不能做到上面的随时随地编写文章，因为他需要我们经常性地手动执行命令，这非常不优雅。如果你想随时随地及时地编写博客，少敲命令，那么你可以继续看下去了。

前期环境准备

任意平台安装即可，我是在 windows 中安装的。

nodejs 安装

参考链接：Node.js 安装配置 | 菜鸟教程

PS： 我使用的是 v22.20.0

验证：

C:\Users\lovone>node –version

v22.20.0
C:\Users\lovone>npm -v

10.9.3

出现版本号说明安装成功。

git 安装

参考链接：Git 安装配置 | 菜鸟教程

验证：

C:\Users\lovone>git -h

usage: git……

搭建 hexo

注意：本文中，后续所有的命令都是在 Git Bash 中敲的。

拉取 hexo

注意：如果 npm 拉取速度比较慢，请自行更换为国内源

1
npm install hexo-cli -g

创建本地环境

创建一个文件夹，用做hexo的根目录并初始化

1
2
3
4
5
6
7
8
9
10
11
12
# 创建hexo文件夹
mkdir hexo
# 进入该文件夹
cd hexo
# hexo初始化
hexo init
# 安装必要的库
npm install
# 生成hexo的静态网页
hexo g
# 本地测试
hexo s


此时会在本地启动一个临时服务器供用户预览，点击提示链接 http://localhost:4000/访问。

创建 github pages 仓库

在github上创建一个公有仓库 ，用来存放博客静态文件。
注意 ：

  1. 该仓库必须是公有仓库（public）
  2. 该仓库的名字必须为 [你的 github 用户名].github.io

然后在该仓库中，点击 Settings -> Pages，按照如图配置即可。

5-创建github pages

域名解析的题外话

如果你在国内已经有了域名，无论是否备案了，都可以解析到 github pages。只需要在上面的 Custom domain 中填写你的域名即可。（这里有点记不清了……）

配置hexo-deploy

安装hexo-deploy工具

1
npm install hexo-deployer-git --save

编辑 hexo 的 _config.yaml 文件

编辑 hexo 的 _config.yaml 文件，在末尾的deploy 处添加以下内容（注意：deploy 字段只能有一个）

1
2
3
4
deploy:
  type: git
  repo: git@github.com:你的用户名/你的用户名.github.io
  branch: main

部署到 github

配置git

1
2
git config --global user.name "你的Github用户名"
git config --global user.email "你的Github邮箱"

你可以使用下面的命令查看是否配置成功。

1
2
git config get --global user.name
git config get --global user.email

生成密钥

1
2
3
cd ~/.ssh/                # 切换到用户主目录下的.ssh文件夹（如果没有会自动创建）
ssh-keygen -t ed25519 -C "你的邮箱"  # 使用ed25519算法生成密钥对，并添加邮箱作为注释
cat id_ed25519.pub				# 可以看到因嘎嘎i放在github上的公钥

一路回车，生成的key会保存在你的用户文件夹中的 .ssh文件夹下，公钥为 id_ed25519.pub的文件。
接下来登录Github，在 Settings -> SSH and GPG keys -> new SSH keys选择 Authentication Key上传公钥内容。

测试连接

1
ssh -T git@github.com

Hi 【你的 github 用户名】! You’ve successfully authenticated, but GitHub does not provide shell access.

出现上面的内容，说明已经成功了。

测试部署 hexo 的静态网站

1
hexo g && hexo d

此时，你应该可以访问 https://你的 github 用户名.github.io 来访问到你的博客主页了。

安装主题 butterfly

hexo 社区维护着大量的主题包，此处仅介绍 Butterfly ，其余主题请自行安装和配置

克隆主题 butterfly

在hexo目录下输入以下命令

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

安装 pug 和 stylus 的渲染器

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

应用主题

修改 Hexo 根目录下的 _config.yml，把主题改为 butterfly

1
theme: butterfly

升级建议

为了减少升级主题后带来的不便，请使用以下方法：

在 hexo 的根目录创建一个文件 _config.butterfly.yml，并把目录 themes/butterfly 下的 _config.yml 内容复制到 _config.butterfly.yml 去。

注意：

  1. 不要把主题目录 themes/butterfly 下的 _config.yml 删掉。
  2. 复制的是主题butterfly的 _config.yml ，而不是 hexo 的 _config.yml
  3. 以后只需要在 _config.butterfly.yml 进行配置就行。如果使用了 _config.butterfly.yml， 配置主题的 _config.yml 将不会有效果。

Tips: 此时你可以依次执行命令 hexo clean、hexo g、hexo s，根据提示链接预览主题是否已经更新。

利用 GitHub Actions 进行自动化部署

创建自动化部署 Actions 脚本

在 hexo 的 .github文件夹下新建 workflows文件夹，在该文件夹下创建 main.yml文件，内容如下：

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
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
name: Blog CI/CD # 脚本 workflow 名称
#测试Actions
on:
  push:
    branches: [main, master] # 当监测 main,master 的 push
    paths: # 监测所有 source 目录下的文件变动，所有 yml,json 后缀文件的变动。
      - '*.json'
      - '**.yml'
      - '**/source/**'

jobs:
  blog: # 任务名称
    timeout-minutes: 30 # 设置 30 分钟超时
    runs-on: ubuntu-latest # 指定最新 ubuntu 系统
    steps:
      - name: Checkout code with submodules
        uses: actions/checkout@v4
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          fetch-depth: 1
          submodules: false  # ✅✅ 关键：使用自定义的butterfly主题，该参数必须为false。否则需要为true
  
      - uses: actions/setup-node@v4 # 设置 node.js 环境
      - name: Cache node_modules # 缓存 node_modules，提高编译速度，毕竟每月只有 2000 分钟。
        uses: actions/cache@v4 # 亲测 Github 服务器编译速度比我自己电脑都快，如果每次构建按5分钟计算，我们每个月可以免费部署 400 次，Github yyds！！！
        env:
          cache-name: cache-node-modules
        with:
          path: ~/.npm
          key: ${{ runner.os }}-build-${{ env.cache-name }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            ${{ runner.os }}-build-${{ env.cache-name }}-
            ${{ runner.os }}-build-
            ${{ runner.os }}-
      - name: Init Node.js # 安装源代码所需插件
        run: |
          npm install
          echo "init node successful"
      - name: Install Hexo-cli And component # 安装 Hexo
        run: |
          npm install -g hexo-cli --save
          npm install hexo-generator-sitemap --save
          npm install hexo-generator-baidu-sitemap --save
          npm install hexo-abbrlink --save
          npm install hexo-renderer-pug hexo-renderer-stylus --save
          npm i hexo-renderer-markdown-it --save
          npm install hexo-generator-searchdb
          npm install katex @renbaoshuo/markdown-it-katex
          npm install hexo-wordcount --save
          npm i hexo-filter-nofollow --save
          npm install hexo-generator-feed --save
          # 🔔注意：如果后期还需要增加其他的插件，记得在这里进行添加
          echo "install hexo successful"
      - name: Build Blog # 编译创建静态博客文件
        run: |
          hexo clean && hexo g
          echo "build blog successful"
      - name: Deploy Blog # 设置 git 信息并推送静态博客文件
        run: |
          cd ./public
          git init
          git config user.name "${{secrets.GIT_NAME}}"
          git config user.email "${{secrets.GIT_EMAIL}}"
          git add .
          git commit -m "Update"
          git push --force --quiet "https://${{secrets.GH_TOKEN}}@${{secrets.GH_REF}}" master:main

      - run: echo "Deploy Successful!"

🔔 注意：如果后期还需要增加其他的插件，记得在 50 行前后进行添加

配置私有仓库 Blog-Source

这里实际上在配置博客的源码仓库。后续我们的 Qexo 时直接操作这个源码仓库，在我们增加或修改后，GitHub Actions 会监测到仓库的修改，然后 Actions 会自动执行一系列的操作，而自动执行的这些操作我们是可以自定义的。因此我们可以利用 github 的Actions 重新生成我们的博客并且自动化部署到 github.io。

可以不叫Blog-Source，改成其他名称也行。

新建私有仓库 Blog-Source

如图

连接私有仓库 Blog-Source

由于上面我们连接的是 github.io 的仓库，现在需要将源码推送到Blog-Source，因此需要修改连接仓库的名字。

1
git remote set-url origin https://github.com/你的用户名/Blog-Source.git

配置私有仓库的 Secret。

在Actions 脚本中，我们引入了四个变量，GIT_NAME, GIT_EMAIL, GH_TOKEN,GH_REF，接下来，我们需要在私有仓库 Blog-Source 中配置它们。在 Blog-Source -> Settings -> Secrets and variables -> Actions -> Secrets 中添加用于Github Action的Secrets。

7-配置私有仓库的 Secret

  • GIT_NAME的就是Github账号的用户名
  • GIT_EMAIL就是Github账号所使用的邮箱
  • GH_REF 的内容为 github.com/用户名/用户名.github.io.git
  • GH_TOKEN需要在 Github -> Settings -> Developer Settings -> Personal Access tokens -> Tokens(classic) 获取，选择生成 classic类型的token，为了简便可以把token过期时间设置为 永不过期，权限范围勾选repo和workflow

移除 butterfly 的子模块属性(可选)

注意：移除 butterfly 的子模块属性，主要是为了方便我们后面魔改 butterfly 主题，如果你不需要魔改 butterfly，那么请看第 4.4 步。PS： 本人使用的是 4.3 步骤。

这里需要解释一下这一步：未来我们需要将 hexo 文件夹推送到 github 的 Blog-Source 仓库，而我们是使用 git 安装的Butterfly 主题，这会导致 Butterfly 主题被作为 Git 子模块引入，那么我们修改本地的 Butterfly 主题不会被同步到 github，因为子模块的修改默认不会被主仓库跟踪和部署，因此这里需要移除它的字模块属性。

1
2
3
4
5
6
7
8
9
10
11
12
# 移除子模块记录（不删除文件）
git rm --cached themes/butterfly
rm -rf .git/modules/themes/butterfly

# 删除子模块配置文件中的记录（如果存在）
# 编辑 .gitmodules 文件，删除关于 themes/butterfly 的段落，然后保存

# 将修改后的主题目录添加到主仓库
# git add themes/butterfly
git add .
git commit -m "将主题butterfly目录添加到仓库中"
git push origin main

执行完这一步后，你可以在 Blog-Source 的 Actions 标签下看到执行的过程。

9移除 butterfly 的子模块属性

等待它执行完毕后，就可以访问 https://用户名.github.io看到自己的博客也同步更新了。

将 butterfly 作为子模块(可选)

注意：4.3 和 4.4 二选其一即可。**如果你不确定使用哪个，那么请 和我一样选择 4.3。**按照我的步骤一步一步来。

如果你选择的是 4.4，那么记得修改 4.1 中的 Actions 脚本，将 submodules: false修改为 submodules: true

在 hexo 目录下添加一个文件 .gitmodules

内容如下：它的意思就是将主题butterfly 作为 Git 的子模块引入，后续每次执行 Action 脚本时，会自动从 github 拉取最新的 butterfly 主题。

1
2
3
[submodule "themes/butterfly"]
  path = themes/butterfly
  url = https://github.com/jerryc127/hexo-theme-butterfly.git

部署 Qexo

具体部署方法不再赘述，详情查看Qexo 文档 - 部署

本人直接在公网的 vps 上安装了 docker，利用 docker 安装了 Qexo。在哪里配置都无所谓，成功了就行。

  • 这个 Github 密钥 就是Blog-Source中的GH_TOKEN，如果忘记了就再生成一个。
  • Github 仓库是 Blog-Source
  • 项目分支是 main (不确定就去 github 看一下，一般现在默认的就是 main)
  • 博客路径留空即可。

然后正常情况下就可以登录进入到后台了。

Qexo 的一些配置

现在直接点击新建文章的话，是不能上传图片的，因为截止到目前，我们还没有设置图床（可以理解为图片存放的位置）。

图床配置

既然将免费进行到底，那我们就继续薅 Github 的羊毛，将 Github 的仓库作为我们的图片库。

在 Qexo 上的配置

这里要注意：

  • 保存路径的最前面是不带 /的。
  • 自定义域名这里，直接在域名后面跟 /images/
  • 至于其他参数的含义，请参考：Qexo 文档 - 图床配置
创建 images 文件夹

保存路径中，我们只有 source 文件夹，但是没有 images 文件夹，我们需要新建它。本地新建文件夹后，放入一张图片，推送到远程即可。

1
2
3
4
5
6
# 在hexo文件夹下执行命令
mkdir source/images
# 由于空文件夹不会被 Git 跟踪，我们需要放一张图片进images文件夹下
git add .
git commit -m "新增了images文件夹"
git push origin main
测试能否上传图片

再 Qexo 中新建一篇文章，然后在图示的地方上传图片即可测试。

结语

到这里，自动化的过程基本就搭建完毕了，后续就是美化和魔改工作了。