博客迁移 Astro 并接入 Qexo 3.7.0 后台折腾手记

一直以来，对于静态博客的折腾似乎总有一种停不下来的魔力。从早期的 Hexo 搭配各种主题，到后来对现代化组件化架构的向往，总觉得博客不仅是文字的容器，也是技术审美的自留地。

最近关注到 Qexo 发布了 3.7.0 新版本，其中最让人眼前一亮的就是终于原生支持了 Astro！这对于一直想尝试 Astro 现代轻量化体验，又舍不得 Qexo 网页端便捷管理后台的我来说，简直是久旱逢甘霖。

趁着周末的闲暇，索性一不做二不休，把博客整个迁移到了 Astro（选用了一款心仪的 Astronauts 主题），并顺势部署了最新版的 Qexo 后台进行现代化管理。在此记录下整个折腾的过程，也给同样想折腾的朋友做个参考。

为什么选择 Astro 与 Qexo 3.7.0？#

在动手之前，先简单聊聊这次技术栈变动的初衷：

Astro 的现代化体验：相比传统 SSG，Astro 带来了极佳的组件化架构和零客户端 JavaScript 默认哲学，构建速度极快，页面轻量清爽，非常适合追求极致性能的个人独立博客。^^
Qexo 3.7.0 的完美适配：以往 Qexo 对 Hexo、Halo 等支持较多，而 3.7.0 版本的更新对 Astro 的内容结构、Frontmatter 以及发布流程有了更好的兼容，使得“网页端随时随地写文章/改文章”的梦想照进现实。
云端无缝协作：采用 Vercel 托管前端、GitHub 进行源码同步、结合 Qexo 后台与 PostgreSQL 数据库，整个链路完全跑通，免去了本地环境的束缚。

整个过程大致可以分为三个核心步骤：部署 Astro 主题、配置 Qexo 后台，以及打通两者的关联。

首先在 GitHub 上准备好基于 Astro 的博客仓库（以 Astronauts 主题为例）：

仓库关联：将项目推送到 GitHub，直接在 Vercel 中导入该仓库进行一键托管部署。
内容适配：检查 src/content/posts 下的 Markdown/MDX 文件结构，确保 Frontmatter 包含必要的字段（如 title, published, description, tags 等）。
日期与 Schema 校验：在对接后台时，建议在 Astro 的内容集合（Content Collections）中对日期字段做好处理（例如使用 z.coerce.date()），以防后台提交的时间格式引起构建报错。

Qexo 的部署依然保持了一贯的轻量与灵活。这次我们将其部署在 Vercel 上，并连接到 PostgreSQL 数据库：

新建数据库：在 Vercel 或其他托管平台准备好 PostgreSQL 数据库实例。
Fork / 部署 Qexo：将 Qexo 源码部署到 Vercel，配置好环境变量：
- DATABASE_URL：连接你的 PostgreSQL 数据库。
- 其他安全与鉴权密钥。
初始化后台：访问部署好的域名，完成管理员账号的注册与初始化。

进入 Qexo 3.7.0 的后台设置，核心是配置好 GitHub 图床/仓库同步 以及 Astro 的API/Webhook 触发：

仓库连接：填入你的 GitHub 仓库信息、Personal Access Token（PAT），让 Qexo 能够直接读写仓库中的文章 Markdown 文件。
分支与路径映射：指定文章存放的对应目录（例如 src/content/posts/）。
自动触发构建：开启 Vercel 的 Deploy Hooks（部署钩子），这样每次在 Qexo 后台点击发布或修改文章时，都能自动触发 Vercel 重新编译部署，实现“网页端保存 $\rightarrow$ 自动同步 GitHub $\rightarrow$ 瞬间完成上线”的丝滑闭环。

在实际联调过程中，也遇到了一点小波折：由于 Astro 对文章 Frontmatter 的日期类型检查比较严格，如果后台提交的日期格式与本地定义的 Zod Schema 稍有出入，Vercel 构建时就会抛出类型错误。

解决办法：在 Astro 的 config.ts 中调整内容集合的 Schema 定义，针对日期字段加入类型强转（例如 z.coerce.date()），这样无论通过 Qexo 后台以何种时间格式写入，都能被正确解析，再也不用担心莫名其妙的构建失败了。

折腾完毕，看着新版博客在轻盈的加载动画中缓缓展开，后台也能随时随地用手机或网页顺畅地敲字、修改、发布，这种掌控感和新鲜感确实让人心情愉悦。

技术总是不断向前，工具也在变得越来越聪明。愿这片赛博空间能承载更多安静的文字、绵长的思绪，以及对代码和生活纯粹的热爱。

晚安，世界。 🌙

如果你在部署 Qexo 3.7.0 或迁移 Astro 的过程中遇到了什么问题，欢迎在评论区一起交流探讨！