鉴于 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按钮即可以成功部署了。

初始化 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 的官方客户端从此下载。

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，然后我们将下面的代码复制进来：

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

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 即可。例如这样：

1
2
3
4
5

- 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, 你就可以在你得博客地址看到你得博客上线了。

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