🚀 Qexo 详细使用教程

适合人群：博客作者 / Hexo 用户 / 想要可视化管理博客的开发者
核心价值：让你告别命令行，像 CMS 一样管理静态博客

---

📌 一、Qexo 是什么？

Qexo 是一个开源的 静态博客管理系统，可以理解为：

👉 给你的 Hexo / Hugo 博客加一个「后台管理界面」

你可以通过网页实现：

• ✍️ 写文章（富文本/Markdown）
• 🖼️ 上传图片
• 🏷️ 分类标签管理
• 🚀 一键发布到 GitHub Pages
• 🔄 自动同步仓库

---

🧠 二、Qexo 的核心优势

功能	说明
🖥️ 可视化编辑	不再依赖 CLI
🔄 Git 自动同步	自动 push 到 GitHub
📦 多框架支持	Hexo / Hugo
🌐 在线部署	支持 Vercel / Docker
🔐 登录系统	支持 GitHub OAuth

---

🏗️ 三、系统架构理解（重要）

Qexo 本质上是：

浏览器 → Qexo 后台 → GitHub 仓库 → 静态博客（Hexo）

👉 Qexo 不存文章，而是帮你操作 Git 仓库

---

⚙️ 四、部署方式选择

✅ 方式一：Vercel 部署（最简单）

适合：新手 / 不想运维

步骤：

1️⃣ Fork Qexo 仓库

2️⃣ 打开 Vercel

3️⃣ 导入 GitHub 项目

4️⃣ 配置环境变量：

GH_TOKEN=你的GitHub Token
REPO_NAME=用户名/仓库名
BRANCH=main

5️⃣ 一键部署 🎉

---

✅ 方式二：Docker 部署（推荐）

适合：服务器用户

docker run -d \
  -p 3000:3000 \
  -e GH_TOKEN=你的token \
  -e REPO_NAME=用户名/仓库 \
  -e BRANCH=main \
  --name qexo \
  qexo/qexo

访问：

http://服务器IP:3000

---

✅ 方式三：本地运行

git clone https://github.com/am-abudu/Qexo.git
cd Qexo
npm install
npm run dev

---

🔑 五、GitHub Token 获取

进入：

👉 GitHub → Settings → Developer settings

创建 Token，勾选：

• ✅ repo
• ✅ workflow（推荐）

---

🧩 六、绑定 Hexo 博客

仓库需要满足：

your-blog/
├── source/_posts/
├── themes/
├── _config.yml

👉 Qexo 会直接操作：

source/_posts/*.md

---

✍️ 七、写文章流程

进入 Qexo 后台：

1️⃣ 新建文章

• 标题
• 分类
• 标签
• 内容（Markdown）

2️⃣ 自动生成 Front-matter

title: 我的第一篇文章
date: 2026-03-22
tags:
  - 教程

3️⃣ 点击发布

👉 Qexo 自动执行：

git add .
git commit -m "new post"
git push

---

🖼️ 八、图片上传配置

默认支持：

• ✅ GitHub 图床
• ✅ 本地路径

推荐配置：

post_asset_folder: true

---

🔄 九、自动部署（CI/CD）

推荐结合：

👉 GitHub Actions

示例 .github/workflows/deploy.yml：

name: Deploy Hexo

on:
  push:
    branches:
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3
      - name: Install
        run: npm install
      - name: Generate
        run: npx hexo generate
      - name: Deploy
        run: npx hexo deploy

---

🔐 十、登录系统（GitHub OAuth）

Qexo 支持 GitHub 登录：

你需要配置：

GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

---

🎨 十一、进阶玩法

🚀 1. 多环境管理

• ✅ dev 分支 → 测试
• ✅ main 分支 → 生产

---

🧠 2. 自动草稿系统

可扩展：

• ✅ 定时发布
• ✅ 草稿箱

---

📊 3. 数据统计

结合：

• ✅ Google Analytics
• ✅ Umami

---

⚠️ 十二、常见问题

❓ 1. 无法 push

👉 检查：

• Token 权限
• 仓库名称

---

❓ 2. 页面空白

👉 检查：

• 环境变量
• API 请求是否成功

---

❓ 3. Hexo 未更新

👉 原因：

• 没有触发 CI
• deploy 配置错误

---

🧩 十三、与 Hexo CLI 对比

功能	Hexo CLI	Qexo
写文章	❌ 命令行	✅ 可视化
发布	手动	自动
图片管理	麻烦	简单
新手友好	❌	✅

---

📚 相关资源

资源	链接
Qexo GitHub	https://github.com/am-abudu/Qexo
Qexo 官网	https://oplog.cn/qexo/
Hexo 官网	https://hexo.io

---

作者：iomelons
博客：https://iomelons.github.io
GitHub：https://github.com/iomelons