如何是用PageCMS来管理FireFly博客
给 Firefly 博客加上 Web 管理后台：PageCMS 配置实录
起因：静态博客的”写作体验”问题
用 Firefly 搭博客已经有一段时间了，这套基于 Astro 和 Fuwari 二开的主题颜值真的没话说。但静态博客的问题一直在困扰我：
- 想写篇文章，得打开电脑 → 拉仓库 → 新建 md → 手写 frontmatter → 提交；
- frontmatter 字段一多（
published、tags、category、image……），手写容易出错； - 手机上突然有了灵感？基本没戏。
所以一直在找一款”不给架构添负担”的管理方案。直到遇到了 Pages CMS。
Pages CMS 是什么
Pages CMS 是一个开源的、面向 GitHub 仓库的内容管理系统，它的核心理念非常极客：
你的仓库就是数据库，配置文件就是唯一的配置。
它不依赖任何第三方服务存数据，所有内容最终都以 Markdown 文件的形式存在于你的仓库里。整个系统的核心就是仓库根目录下的一个 .pages.yml 文件。它按仓库、按分支读取这个配置，然后生成对应的管理界面。
对静态博客来说，这几乎是完美方案：
- ✅ 不改博客架构，不动一行 Firefly 的代码；
- ✅ 编辑保存就是 git commit，天然有版本记录；
- ✅ 部署流程完全不变（Cloudflare Pages / Vercel 监听仓库自动构建）；
- ✅ 支持自托管，也可以直接用官方托管版。
准备工作
开始之前，先确认你的 Firefly 仓库结构（默认安装的话应该长这样）：
├── public/│ └── assets/ # 站点根静态资源，图片放这里└── src/ ├── content/ │ ├── posts/ # 文章（md/mdx，支持子目录） │ ├── dynamic/ # 动态/碎碎念，文件名如 2026-07-15-010756.md │ └── spec/ # 独立页面（about、friends、guestbook） └── config/ # 主题配置（TypeScript）另外需要准备一个 GitHub 账号，博客仓库在上面就行。
第一步：安装 GitHub App
- 打开 app.pagescms.org，用 GitHub 登录；
- 按引导安装 Pages CMS 的 GitHub App，只授权博客这一个仓库就够了，权限最小化比较安心；
- 安装完成后，在面板里选择你的仓库和要管理的分支（一般就是
master或main）。
到这里还没有任何可用内容——因为你还没告诉它内容在哪。接下来就是重头戏。
第二步：编写 .pages.yml
在仓库根目录新建 .pages.yml。整个文件由几部分组成：media（媒体）、content（内容定义）、可选的 settings 和 actions。
下面是我按 Firefly 实际结构写好的完整配置，可以直接抄：
media: input: public/assets/images # CMS 上传的图片存到仓库这个目录 output: /assets/images # 写入文章中的 URL 前缀
content: # ============ 内容 ============ - name: blog label: 内容 type: group items: # ---- 文章 ---- - name: posts label: 文章 type: collection path: src/content/posts subfolders: true # Firefly 允许子目录 view: primary: title sort: published order: desc filename: template: "{primary}.md" field: create # 新建时显示文件名输入框，方便改成英文 slug fields: - name: title type: string required: true - name: published type: date required: true options: format: yyyy-MM-dd - name: updated type: date options: format: yyyy-MM-dd - name: description type: text label: 摘要 - name: image type: image label: 封面图 - name: tags type: string list: true - name: category type: string - name: draft type: boolean label: 草稿 - name: pinned type: boolean label: 置顶 - name: slug type: string pattern: "^[a-z0-9-]*$" - name: password type: string label: 加密密码 - name: passwordHint type: string label: 密码提示 - name: body type: rich-text label: 正文
# ---- 动态 ---- - name: dynamic label: 动态 type: collection path: src/content/dynamic filename: "{year}-{month}-{day}-{hour}{minute}{second}.md" view: sort: published order: desc fields: - name: published type: date required: true options: time: true format: yyyy-MM-dd HH:mm:ss - name: body type: rich-text label: 内容
# ---- 独立页面 ---- - name: spec label: 独立页面 type: collection path: src/content/spec exclude: ["friends.mdx"] # 友链页是 MDX，不适合结构化编辑 fields: - name: title type: string - name: description type: string - name: body type: rich-text提交这个文件后，回到 Pages CMS 面板刷新，左侧就能看到”文章 / 动态 / 独立页面”三个栏目了。
关键配置逐条解释
1. 媒体：media
Firefly 的封面图支持三种写法：https:// 外链、/ 开头的 public 目录路径、相对 md 文件的本地路径。CMS 上传走的是第二种——图片存到 public/assets/images/，文章里写入 /assets/images/xxx.png，正好能被 Astro 识别。
⚠️ 注意：已有文章里
./images/xxx.avif这种相对路径引用不受影响，但那些图片不在public/里，CMS 管理不到，这是正常的。
2. 文章集合：字段与 Firefly frontmatter 一一对应
.md 文件默认按 yaml-frontmatter 格式解析，所以不用写 format。有个特殊字段 name: body，它自动对应 frontmatter 之后的正文部分，富文本编辑器的内容就写进去。
tags 用了 list: true，表示数组字段，对应 Firefly 的 tags: [前端, 开发] 写法。slug 加了正则 ^[a-z0-9-]*$，防止手滑输入大写和空格，毕竟它直接决定文章 URL。
3. 动态：文件名模板的巧思
Firefly 的动态文件名格式是 2026-07-15-010756.md。Pages CMS 的文件名支持时间 token，一行就还原了这个规则：
filename: "{year}-{month}-{day}-{hour}{minute}{second}.md"4. 独立页面：记得排除 MDX
friends.mdx 里包含 JSX 代码，结构化编辑器搞不定它，用 exclude 排除掉就好。about、guestbook 这类纯 Markdown 页面可以正常编辑。
踩过的坑
坑一：想管理 src/config/*.ts 主题配置。
Firefly 的站点设置是 TypeScript 代码，不是数据文件。Pages CMS 确实可以用 format: code 把它作为纯代码文件打开：
- name: site-config label: 站点设置 type: file path: src/config/siteConfig.ts format: code但改错一个逗号构建就挂了，我最后还是把这段删了。主题配置还是在 IDE 里改比较稳。
坑二：中文标题直接当文件名。
filename 里的 {primary} 默认取标题，中文标题会生成中文文件名。所以我给文章集合用了：
filename: template: "{primary}.md" field: create # 新建时显示文件名输入框这样新建文章时会弹出文件名输入框，手动填英文 slug 即可。
坑三：忘记提交到正确的分支。
.pages.yml 是按仓库和分支读取的。如果你的面板连的是 master，配置却提交到了别的分支，面板是认不出来的。
实际体验
配置完成后的写作流程变成了：
- 打开 Pages CMS → 点”新建”；
- 填标题、日期、标签，正文在富文本编辑器里写，图片直接从媒体库选或上传；
- 点保存。
然后仓库里就多了一次 commit，部署流水线自动跑，几分钟后文章就上线了。手机上也能完成同样的操作——这就是我一直想要的。
而且因为所有变更都是 git commit，手滑删错了也能从历史记录里找回来，这种安全感是很多 SaaS 型 CMS 给不了的。
总结
- Pages CMS 通过一个
.pages.yml文件就能给任意 GitHub 仓库套上管理界面，零侵入、数据完全自主； - 对 Firefly 这类 Fuwari 系 Astro 博客，文章、动态、独立页面都能被很好地管理；
- 媒体建议统一走
public/目录；TypeScript 主题配置不建议交给 CMS； - 如果你也在用 Firefly，上面那份配置拿走改改就能用。
折腾的意义不就在于此嘛：花一个下午配置好工具，换来以后每一次写作的心流💗。
参考链接：
文章分享
如果这篇文章对你有帮助，欢迎分享给更多人！