SveltiaCMS与Hexo集成

狂犬主子2026-07-292026-07-29

其实狗子是有想写博客的，但是由于在电脑上打字比较不方便——一般想写点什么的时候，电脑又不在身边，所以就很少写文章。

最近发现可以使用 git-based CMS，实现自动推送文章到 GitHub 仓库，经过一定的技术选型，最终选用了 Sveltia CMS。

配置

因为不同博客系统的配置不一样，像我使用的 Hexo，Sveltia CMS 官网没有文档。不过好在现在 AI 很发达，其实让 AI 自己弄就好了。

首先随便找个能联网的 Chat AI 大致了解一下这个项目，然后让它生成一下提示词，粘贴给 Coding Agent 生成一下配置就搞好了。

你是一名资深 Hexo、Git-based CMS、Sveltia CMS 和 Cloudflare Pages 工程师。

我有一个现有 Hexo 博客，需要迁移接入 Sveltia CMS，请帮我完成方案设计和实际修改指导。

当前架构：

- 静态博客框架：Hexo
- 仓库：GitHub 私有仓库
- 部署：Cloudflare Pages 自动构建
- 构建方式：git push 后 Cloudflare Pages 执行 hexo generate
- 不希望改变现有发布流程

当前目录结构：

source/
├── _posts/
│   ├── test.md
│   └── test/
│       └── image.png
│
├── admin/
│   （目前不存在，需要创建）

Hexo 配置：

已开启：

post_asset_folder: true

文章资源采用 Hexo Post Asset Folder 模式。

当前文章示例：

文件：

source/_posts/test.md

资源：

source/_posts/test/image.png


Markdown 图片引用目前可能是：

![图片](./test/image.png)

或者：

![图片](test/image.png)

请考虑迁移后是否应该调整为 Hexo 推荐形式：

![图片](image.png)

或者：

{% asset_img image.png %}


目标：

我要在 Hexo 博客中加入 Sveltia CMS，实现：

1. 浏览器访问：

https://我的域名/admin/

可以进入 Sveltia CMS 后台。

2. 使用 GitHub backend：

- 操作私有 GitHub 仓库
- CMS 修改内容后自动 commit 到 main 分支
- 保持 Cloudflare Pages 自动部署流程不变

3. CMS 管理：

- 创建文章
- 编辑文章
- 修改 front matter
- 上传图片

4. 最重要：

保持 Hexo Post Asset Folder 结构：

创建文章：

test.md

上传图片：

image.png

最终 Git 仓库希望得到：

source/_posts/
├── test.md
└── test/
    └── image.png


请重点研究并使用 Sveltia CMS 官方文档中的 internal media 功能：

https://sveltiacms.app/en/docs/media/internal

确认是否可以使用：

- media_folder
- public_folder
- {{filename}}
- entry-relative media folder

实现：

当前文章 slug 自动对应图片目录：

source/_posts/{filename}/


不要简单建议改成：

source/images/

因为我需要保留 Hexo 原生文章资源目录。


请输出：

1. 推荐迁移方案
2. 完整 source/admin/index.html
3. 完整 source/admin/config.yml
4. GitHub OAuth 配置步骤
5. Cloudflare Pages 是否需要修改
6. Hexo 图片引用是否需要调整
7. 如果 Sveltia 原生无法完全支持，请给出最小改动方案（例如脚本、hook、GitHub Action），不要改变整体架构
8. 给出迁移后的完整目录结构示例

注意：

- 不要重新设计我的博客架构
- 不要引入数据库 CMS
- 不要使用 WordPress、Strapi 等方案
- 优先保持现有 Hexo + GitHub + Cloudflare Pages 流程
- 配置必须可以实际运行，不要只给概念说明

好处

这套 CMS 系统解决了我最头疼的两个问题。

图片资源管理

之前写博客最头疼的就是插图片，因为一些经历，导致狗子不敢使用图床。现在存放图片都是遵循 Hexo 的管理样式：一篇文章对应文章同名目录下的图片。但是每次更换电脑都需要在 Typora 下配置文件存储方式，这就有点麻烦。

这个 CMS 支持自动上传管理图片，所以刚好适合我这种不使用图床，使用纯仓库的方式来管理博客文章还有资源的用户。当然它也支持 S3 上传，但貌似不支持自行托管的 S3。不过大多数自己写博客的一般还是会用 Cloudflare R2，这种它也是支持的。

文档修改管理

事实证明，狗子使用静态博客是对的。动态博客的话，PHP 系的，WordPress 一大堆漏洞，Typecho 也好不到哪里去。动态的有个 Halo，个人体验了一下，感觉还可以，但因为个人平时都习惯使用 Markdown，那种传统的 Prose 反而用不习惯。而且搭建博客还要准备一台服务器，麻烦得要死。当然，Serverless 的方案也有很多，有一些是 Workers 边缘渲染，不过个人不太喜欢。个人最讨厌的就是那种限制访问次数、限制流量的东西。而且那些方案即使在你自己的服务器上跑，由于本来就不是为你自己服务器搭建而设计的，到时候弄出来因为服务器配置不够，用户访问一多卡得要命，缓存还不好配置（比如评论区🐛）。所以，我是非常反感这种边缘渲染、服务端渲染的 JS 框架的。所以博客这种东西，到最后 SSG 是正确的，该静静该动动。打包速度反而不用操心，实在不行到时候换 Hugo，挑个前端写得好的 AI 重新构建一下就可以了。反正博客这种东西，纯 CSS 就可以实现，基本上用不到 JS 就可以把文章文字显示出来。不过一般也到不了那么多文章。

但静态博客最大的问题就是缺乏内容管理系统，也就是没有一个界面去管理文章和数据。因为狗子在写 Markdown 的时候，尤其是一些偏向内容的，还是比较习惯于使用 Typora。虽然现在主力都用 VS Code，但没有图片资源默认存放路径的设置，反而是用 Typora 写有图片的文章比较方便。

一点小插曲

在搞这个 CMS 的过程中遇到了一些问题。其中最头大的就是那个静态资源路径的管理（图片）。我在 CMS 中上传的图片，还有之前已经传过的图片，出现了无法解析路径并显示的问题。

我的这种静态资源管理方法在文档里面并没有现成的案例。也就是说，没有人测试过。这些配置都是 AI 自动帮我生成出来的，好在它的配置文件是有 YAML Schema 的，至少核对了一遍，配置没有问题。尝试让 AI 修复根本无法修好，甚至 AI 把我的配置重写了一遍，把之前的一些都给改乱了。还好我的仓库有 git 提交，给它恢复回来了。

经过进一步人工排查，猜测是 CMS 程序存在 bug。随后让 AI 把 CMS 的仓库拉下来扫描了一遍，果真和我猜想的一模一样：它的路径不会解析模板字符串，导致 CMS 里面无法显示图片，但实际上上传的路径是对的。

于是就直接给 CMS 仓库提 issues。作者是日本人，也不知道是什么时区，我提 issues 的时间有点非人类，但是挺快速的，他 30 分钟左右就修好并发新版，点赞👍！