🚀 Hexo+Qexo全自动化博客搭建教程

📖 方案概述

🎯 核心架构

本部署方案为全自动化方案，支持在线编辑发布博客文章，第一次部署流程较长，请耐心阅读。

前端部署：Hexo博客部署在Github上，一个私有库一个公共库
私有库：存放博客源文件，当源文件检测到更改触发Github Action自动编译源文件并推送到公共库中
公共库：生成Github Page(也可推送到其他静态网页托管商，例如Cloudflare Page)
后端管理：使用Qexo，部署在Vercel或者任意VPS上，提供博客文章管理和撰写功能

✨ 方案优势

🌟 优点

静态博客：维护简单，没有服务器负载压力，尽管专心写手头文章
零成本：天天摸鱼也没有后顾之忧🥰
主题丰富：主题种类丰富，可配置选项多
自动化部署：支持在线编辑，自动构建发布

⚠️ 缺点

交互性较低：相比动态博客，交互性少一些，使用体验略低
配置复杂：在线编辑文章需要独立后端，首次配置麻烦

🛠️ 环境准备

📋 预先准备

✅ 安装Git、Node.js
✅ 一个Github账号
✅ 一个Vercel账号
✅ 一个域名（可选）

📦 Hexo基础安装

1️⃣ 安装Hexo CLI

首先确保已经安装Node.js，安装hexo的命令行工具和git部署工具：

1	npm install hexo-cli -g

💡 提示：如果拉取速度过慢，自行查阅npm更换国内源

2️⃣ 创建本地环境

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

mkdir hexo
cd hexo
hexo init
npm install
hexo g

3️⃣ 重要目录说明

目录	用途
`./public`	用于存放生成的静态网页文件
`./source`	博客内容相关源文件，如 `./source/_post`是博客文章markdown源文件
`./theme`	博客主题
`./_config.yml`	博客配置文件，类似的 `./_config.xxx.yml`为主题配置文件

4️⃣ 本地启动测试

hexo s

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

🔗 部署到Github

1️⃣ 配置Git

首先确保已经安装git，接下来连接github：

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

2️⃣ 生成密钥

1 2	cd ~/.ssh/ ssh-keygen -t ed25519 -C "你的邮箱"

💡 提示：一路回车就行了，生成的key会保存在你的用户文件夹中的 .ssh文件夹下，公钥为 id_xxx.pub的文件

3️⃣ 上传公钥到Github

登录Github，在 Settings -> SSH and GPG keys -> new SSH keys选择 Authentication Key上传公钥内容

4️⃣ 测试连接

1	ssh -T git@github.com

确认之后如果有 Hi xxx! ...的输出，就证明已经连接上了github

5️⃣ 创建仓库

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

6️⃣ 配置Hexo部署

安装hexo-deploy工具：

1	npm install hexo-deployer-git --save

编辑hexo目录中的配置文件 _config.yaml，在末尾加入以下内容：

deploy:
  type: git
  repo: git@github.com:你的用户名/仓库名.git
  branch: main

7️⃣ 一键部署至Github

1	hexo g && hexo d

8️⃣ 创建文章

1	hexo new "新文章"

生成的文章会保存在本地 ./source/_post下面，然后使用文本编辑器手动编辑完成后再一键部署至Github

🎨 主题安装(Butterfly)

1️⃣ 安装主题

在hexo目录下输入以下命令：

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

2️⃣ 配置主题

在hexo根目录下的 _config.yml配置文件中把 theme改为 butterfly：

1	theme: butterfly

3️⃣ 创建主题配置文件

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

到这里Butterfly已经安装完毕，可以继续进行教程，后续主题配置请自行参考butterfly官网在 _config.butterfly.yml中进一步设置

🌐 配置Github Page

1️⃣ 启用Page

进入Github仓库，Settings->Pages，在 source一栏选择 Deploy from a brach

2️⃣ 设置分支

在下方 branch选择 main->root，这样设置以后，仓库会在监测到提交后自动把仓库内的静态页面文件部署为Github Page

3️⃣ 自定义域名

免费提供一个子域名访问，如有需要可以在下方 Custom Domain配置自定义域名

⚙️ 部署Hexo到Github实现自动化

1️⃣ 创建私有仓库

新建私有仓库 Blog-Source，用于存放Hexo源文件

2️⃣ 连接Blog-Source存储库

1	git clone git@github.com:你的用户名/你的存储库名称.git

3️⃣ 复制文件

连接上后，再复制部分本地hexo文件夹下的必要文件到 Blog-Source下

💡 建议：在此时已经至少选择好主题并下载，此处的 _config.xxx.yml和 themes为主题文件

4️⃣ 配置Github Action

首先在 Github -> Blog-Source -> Actions 中启用Github Action，再在本地 Blog-Source/.github/workflows下添加一个Github Action的配置文件 main.yml：

name: Blog CI/CD

on:
  push:
    branches: [main, master]
    paths:
      - '*.json'
      - '**.yml'
      - '**/source/**'

jobs:
  blog:
    timeout-minutes: 30
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      
      - name: Cache node_modules
        uses: actions/cache@v4
        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
        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
        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!"

⚠️ 注意：由于我直接粘贴的自己的配置文件，所以在名为 Install Hexo-cli And component的任务下方有大量npm包的安装，这些除了前文所述的hexo安装以外，还有额外的一些插件模块，不过由于这些命令直接运行在Github Action的服务器上，所以此处不会产生明显可见的开销，后续搭建完成后自行进一步配置hexo时需要额外插件时请记得在这里检查并加入所需插件

5️⃣ 配置存储库Secrets

出于安全考虑，在上方Github Action的配置文件 Deploy Blog中引用了4个 Secret，分别是 GIT_NAME, GIT_EMAIL, GH_TOKEN, GH_REF，接下来将在存储库中设置它们

在 Github -> Blog-Source -> Settings -> Secrets and variables -> Actions -> Secrets 中添加用于Github Action的Secrets

Secret名称	内容说明
`GIT_NAME`	Github账号的用户名
`GIT_EMAIL`	Github账号所使用的邮箱
`GH_TOKEN`	需要在Github -> Settings -> Personal Access tokens获取
`GH_REF`	格式为 `github.com/用户名/Blog仓库名.git`

获取GH_TOKEN

在Github -> Settings -> Personal Access tokens获取，选择生成 classic的token，为了简便可以把token过期时间设置为永不过期，权限范围勾选repo和workflow

生成的token即为 GH_TOKEN的内容

设置GH_REF

GH_REF的内容为 github.com/用户名/Blog仓库名.git

⚠️ 重要：这里的仓库是之前的用于存放静态页面文件的Blog仓库名称，而不是存放hexo源文件的Blog-Source仓库名

6️⃣ 同步本地Blog-Source更改

1
2
3

git add .
git commit -m "init"
git push -u

完成之后应该可以在Github -> Blog-Source里面看到刚才的文件，此时可以编辑本地 /Blog-Source/source/post里面的文章，再使用上述命令提交，到Github Blog-Source仓库查看Github Action是否正常运行

🚀 通过Vercel部署Qexo

1️⃣ 一键部署

首次部署会报错, 请无视并进行接下来的步骤

2️⃣ 配置Vercel PostgreSQL

点击 Storage -> Create Database -> Neon (PostgreSQL)，选择Washington, D.C., USA (East) - iad1位置的数据库，创建完毕后点击Connect Project连接到你第一步创建的项目

3️⃣ 重新部署

点击Overview回到刚才创建的项目，Development -> Redeploy，等待配置完成若没有错误即可进入初始化引导

4️⃣ 自定义Vercel域名

在上方创建的vercel项目中，点击 Settings-> Domains添加自定义域名，通过CNAME解析到vercel即可使用自定义域名访问

🔧 Qexo初始化配置

1️⃣ 配置Github密钥

Github密钥即为之前在Blog-Source中Secret填入的 GH_TOKEN的值，没有保存也可按上方再申请一个

2️⃣ 配置Github仓库

这里的Github仓库为存储hexo源文件的仓库，格式为 用户名/仓库名，项目分支 main

3️⃣ 完成配置

设置完毕应该可进入Qexo，至此Blog搭建完成，可以直接在Qexo上撰写文章，有关Qexo和Hexo以及主题的配置，请自行查阅官方网站

📊 方案运行流程回顾

graph LR
    A[Qexo编辑文章] --> B[提交到Blog-Source]
    B --> C[Github Action触发]
    C --> D[Hexo编译生成静态文件]
    D --> E[推送到Blog仓库]
    E --> F[Github Page自动部署]
    F --> G[博客更新完成]