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

🚀 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部署工具：

npminstallhexo-cli-g

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

2️⃣ 创建本地环境

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

mkdirhexocdhexo hexo initnpminstallhexo g

3️⃣ 重要目录说明

此时文件目录下一些比较重要的文件目录有：

4️⃣ 本地启动测试

hexo s

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

🔗部署到Github

1️⃣ 配置Git

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

gitconfig--globaluser.name"你的Github用户名"gitconfig--globaluser.email"你的Github邮箱"

2️⃣ 生成密钥

cd~/.ssh/ ssh-keygen-ted25519-C"你的邮箱"

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

3️⃣ 上传公钥到Github

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

4️⃣ 测试连接

ssh-Tgit@github.com

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

5️⃣ 创建仓库

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

6️⃣ 配置Hexo部署

安装hexo-deploy工具：

npminstallhexo-deployer-git--save

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

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

7️⃣ 一键部署至Github

hexo g&&hexo d

8️⃣ 创建文章

hexo new"新文章"

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

🎨主题安装(Butterfly)

1️⃣ 安装主题

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

gitclone-bmaster https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly

2️⃣ 配置主题

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

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存储库

gitclone 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/CDon:push:branches:[main,master]paths:-'*.json'-'**.yml'-'**/source/**'jobs:blog:timeout-minutes:30runs-on:ubuntu-lateststeps:-uses:actions/checkout@v4-uses:actions/setup-node@v4-name:Cache node_modulesuses:actions/cache@v4env:cache-name:cache-node-moduleswith:path:~/.npmkey:${{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.jsrun:|npm install echo "init node successful"-name:Install Hexo-cli And componentrun:|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 Blogrun:|hexo clean && hexo g echo "build blog successful"-name:Deploy Blogrun:|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

获取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更改

gitadd.gitcommit-m"init"gitpush-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以及主题的配置，请自行查阅官方网站

📊方案运行流程回顾

🎯总结

至此，你已经成功搭建了一个完整的Hexo+Qexo全自动化博客系统！

✅ 完成的功能

• ✅ Hexo静态博客框架
• ✅ Github Actions自动构建部署
• ✅ Qexo在线编辑管理
• ✅ Vercel后端服务
• ✅ 自动化发布流程

🚀 下一步建议

1. 在Qexo中配置主题参数
2. 自定义博客域名
3. 配置CDN加速
4. 添加评论系统
5. 配置分析统计

💡使用建议：这是一个功能强大的博客系统，建议先熟悉Qexo的基本操作，然后再逐步扩展功能。如有问题，请查阅官方文档或社区资源。