鉴于 Qexo 官方文档内容非常简略（简陋），在尝试无数次失败（主要是网上的教程都有很多问题）后，将成功搭建的流程和方法记录在本文中。

在开始之前，我需要简单介绍一下我们云端 Hexo 后台的搭建原理：就是首先你得把所有博客的源代码（是 Hexo源码，不是生成后的静态博客源码）托管到 Github仓库中，然后通过设置一系列的 Key, 允许我们搭建在 Vercel的 Qexo服务可以交互的编辑和提交内容到 Github仓库，这样我们在云端编辑的博文

就可以自动的上传到 Github仓库了，所以这个 Github仓库一定要是私有的，否则你的源码就泄露了。然后我们添加一个 Github Action, 当在云端编辑好了后，我们用 Action来编译出静态博客来推送到 Github Pages. 然后我们可以在 Vercel或者CloudFlare关联我们的 Github Pages，这样相比 Pages会有更好的访问速度和 SEO。

部署 Qexo 环境

官方提供了四种方式来部署 Qexo 环境，其中一种允许你在本地进行部署，另外三种各自使用了不同网站提供的免费数据库服务。综合考虑操作便捷性和成功率，这里选用 Vercel 提供的免费 PostgreSQL 服务进行部署。

首先点击这里进入Qexo 的仓库克界面，我们点击右上角的 Fork按钮将仓库克隆到我们自己的仓库里，然后打开 Vercel登录你得 Github账号，并且使用刚才克隆得仓库来部署一个服务，这样可以让我们及时得同步上游版本，从而更好的更新 Qexo系统版本。

设置好仓库名称后，点击 Create 创建，下边会有一个 Deploy 界面。Vercel 在创建和更改仓库时会自动进行一次部署，因此创建完毕后部署将会自动启动，并且这第一次部署是一定会失败的。因为 Qexo 所依赖的数据库还没有配置。因此点击网页左上角的三角形符号，不出意外的话，界面将是这个样子：

(我这里是已经配置好了 Qexo)

然后我们开始配置 PostgreSQL 数据库，在 Storage 界面可以申请，点击右上角 Create Database并选择 Neon 或者 Supabase，Vercel 使用外部服务提供 PostgreSQL服务，如果你先前没有配置过——点击 Continue进入数据库连接配置，在 Connect界面选择地区为 Washington DC或者 USA (east)。创建完毕后，在 Storage选项卡里选择进入你创建的数据库配置界面。在左侧边栏点击 Project，接着点击 Connect Project：

在上面 Search Projects...选择自己想要部署 Qexo 的仓库即可，Vercel这里的好处就是它可以全自动的执行前端和数据库的链接，可以保证完全正确的链接，这里我们回到项目build界面，点击 Build Logs按钮，点击 Redeploy按钮即可以成功部署了。

这里需要注意的是，因为 Vercel在国内是无法访问的，但是添加一个自定义的域名，然后基于该域名提供的 DNS 服务就可以正确打开了，所以推荐你设置一下自定义域名。添加域名的操作就很简单了，直接点击Settings->Domain就可以了，这里就不再赘述了。

初始化 Qexo

Github配置

部署完毕后，切换到绑定的域名，本例中我们转到 https://admin.xiaohanys.xyz。首先需要你填写用户名和密码，Token留空即可。接下来设置 Github链接，如果你使用 Hexo，并在 Github 上托管，在 Github 的配置界面，你会看到这几项：
‍‍‍‍‍‌‌‌‍

Github 密钥这一项，你需要在Github设置中申请。右上角选择 Generate New Token，有两个选项，选择 classic。接着完成身份验证。改变如下几项：

Note 必填，作为这个token的使用目的；Expiration 是生效期限，安全起见建议设置一个较短的期限，然后定时重置，重新配置Qexo设置，这里我选择的是永久有效；在下边的生效条目里，保证 repo 下的复选框全部勾选，建议同时勾选 workflow，但官方不建议给出所有权限。这么做的目的是保证Qexo有足够权限访问Github API从而在线修改Github博客源码的内容。

申请完毕后复制下来，出于安全，Github仅在token初次创建完毕后给出复制选项，所以尽快保存，并填入初始化界面的“Github 密钥”文本框中。

然后在Github里新建仓库，用于存放博客源码。我建议各位使用 Github官方的客户端来执行仓库推送的过程，用命令难免会出错，出错还不方便 Debug。且如果是 Windows电脑不用安装 Git bash命令了。Github的官方客户端从此下载。

:使用 Github Desktop要做的就是把我们的所有 hexo的源码推送到一个私有的仓库里，刚才设置界面的“Github 仓库”这一项就填刚刚创建并上传的源码仓库，格式是 <username>/<repo>（例：XXX/xiaohanys）。 “项目分支”填源代码仓库的主要分支，一般是 master；“博客路径”留空即可。

Vercel 配置

设置好 Github的链接后就是需要我们设置 Vercel的密钥，“VERCEL_TOKEN”一项，需要在这里生成。

同样是填写 token 名称、生效范围（这里选择 xxx's projetcs）和生效期限（建议期限短些）。完毕后点击 Create 生成密钥，也是需要尽快复制下来，粘贴到“VERCEL_TOKEN”里。

“PROJECT_ID”则需要回到Vercel对应的项目的 Settings 里，在 General 选项卡中向下翻到 Project ID 并复制内容，粘贴到 PROJECT_ID 中就完成 Vercel 配置了。

设置完毕后就可以从 https://admin.xiaohanys.xyz 快捷进入管理界面了。

Github Action

在我们本地的博客源码根目录（就是你执行 hexo clean & hexo g & hexo d 的文件夹）创建一个文件，路径为 .github/workflows/main.yml，然后我们将下面的代码复制进来：

name: auto deploy Hexo

on:
  workflow_dispatch

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: checkout
        uses: actions/checkout@v4
        with:
          submodules: true
  
      - name: install Pandoc
        uses: nikeee/setup-pandoc@v1
  
      - name: setup Node.js 23.10.0
        uses: actions/setup-node@v4
        with:
          node-version: "23.10.0"

      - name: install Hexo CI
        run: |
          export TS='Asia/Shanghai'
          npm install hexo-cli -g

      - name: cache
        uses: actions/cache@v4
        id: cache-dependencies
        with:
          path: node_modules
          key: ${{runner.OS}}-${{hashFiles('**/package-lock.json')}}
  
      - name: install dependencies
        run: |
          # Install Plugins with 'npm install'
  
      - name: install plugins
        if: steps.cache-dependencies.outputs.cache-hit != 'true'
        run: |
          npm install
  
      - name: Generate static pages
        run: hexo generate
  
      - name: Deploy page
        uses: peaceiris/actions-gh-pages@v4
        with:
          personal_token: ${{ secrets.TOKEN }}
          publish_dir: ./public
          external_repository: username/username.github.io #usename改成你的github用户名
          publish_branch: master

这里我们使用手动触发 workflow_dispatch,是因为 Qexo改动一个文件就会push一次代码，比如我们只是创建了一个新的博客文件，还没有写内容，这样就会自动构建一次，非常消耗资源，这也是我觉得需要改进的地方。目前我们只有手动控制才能更加精准。

最后一步将生成的博客内容部署到 Pages，如果你打算直接部署到当前仓库的 gh-pages分支，那么可以不需要添加 external_repository, 你只需要 github_token和 publish_dir 即可。例如这样：

- name: Deploy
  uses: peaceiris/actions-gh-pages@v4
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public

但是如果你打算把博客文章部署到其他的仓库，那么你需要把 github_token改成 personal_token。你可以在此处申请,并尽可能的开通全部读和写的权限，防止失败。

博客生成流程

最后，打开你得 Hexo云端后台，点击文章，新建文章，然后随意写一篇博客，推送到 Github, 然后手动开启 Github Action, 你就可以在你得博客地址看到你得博客上线了。

如果你需要更多的内容，请查询以下的网站：

Qexo文档

https://www.oplog.cn/qexo/

Qexo搭建教程

https://justpureh2o.cn/articles/17536/

actions-gh-pages官放文档

https://github.com/peaceiris/actions-gh-pages

Vercel搭建Hexo后台Qexo的方法