云深听雪

如何是用PageCMS来管理FireFly博客

Fri, 07 Aug 2026 00:00:00 GMT

给 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 仓库结构（默认安装的话应该长这样）：

1
├── public/
2
│   └── assets/            # 站点根静态资源，图片放这里
3
└── src/
4
    ├── content/
5
    │   ├── posts/         # 文章（md/mdx，支持子目录）
6
    │   ├── dynamic/       # 动态/碎碎念，文件名如 2026-07-15-010756.md
7
    │   └── spec/          # 独立页面（about、friends、guestbook）
8
    └── config/            # 主题配置（TypeScript）

另外需要准备一个 GitHub 账号，博客仓库在上面就行。

第一步：安装 GitHub App#

打开 app.pagescms.org，用 GitHub 登录；
按引导安装 Pages CMS 的 GitHub App，只授权博客这一个仓库就够了，权限最小化比较安心；
安装完成后，在面板里选择你的仓库和要管理的分支（一般就是 master 或 main）。

到这里还没有任何可用内容——因为你还没告诉它内容在哪。接下来就是重头戏。

第二步：编写 .pages.yml#

在仓库根目录新建 .pages.yml。整个文件由几部分组成：media（媒体）、content（内容定义）、可选的 settings 和 actions。

下面是我按 Firefly 实际结构写好的完整配置，可以直接抄：

1
media:
2
  input: public/assets/images   # CMS 上传的图片存到仓库这个目录
3
  output: /assets/images        # 写入文章中的 URL 前缀
4

5
content:
6
  # ============ 内容 ============
7
  - name: blog
8
    label: 内容
9
    type: group
10
    items:
11
      # ---- 文章 ----
12
      - name: posts
13
        label: 文章
14
        type: collection
15
        path: src/content/posts
16
        subfolders: true            # Firefly 允许子目录
17
        view:
18
          primary: title
19
          sort: published
20
          order: desc
21
        filename:
22
          template: "{primary}.md"
23
          field: create             # 新建时显示文件名输入框，方便改成英文 slug
24
        fields:
25
          - name: title
26
            type: string
27
            required: true
28
          - name: published
29
            type: date
30
            required: true
31
            options:
32
              format: yyyy-MM-dd
33
          - name: updated
34
            type: date
35
            options:
36
              format: yyyy-MM-dd
37
          - name: description
38
            type: text
39
            label: 摘要
40
          - name: image
41
            type: image
42
            label: 封面图
43
          - name: tags
44
            type: string
45
            list: true
46
          - name: category
47
            type: string
48
          - name: draft
49
            type: boolean
50
            label: 草稿
51
          - name: pinned
52
            type: boolean
53
            label: 置顶
54
          - name: slug
55
            type: string
56
            pattern: "^[a-z0-9-]*$"
57
          - name: password
58
            type: string
59
            label: 加密密码
60
          - name: passwordHint
61
            type: string
62
            label: 密码提示
63
          - name: body
64
            type: rich-text
65
            label: 正文
66

67
      # ---- 动态 ----
68
      - name: dynamic
69
        label: 动态
70
        type: collection
71
        path: src/content/dynamic
72
        filename: "{year}-{month}-{day}-{hour}{minute}{second}.md"
73
        view:
74
          sort: published
75
          order: desc
76
        fields:
77
          - name: published
78
            type: date
79
            required: true
80
            options:
81
              time: true
82
              format: yyyy-MM-dd HH:mm:ss
83
          - name: body
84
            type: rich-text
85
            label: 内容
86

87
      # ---- 独立页面 ----
88
      - name: spec
89
        label: 独立页面
90
        type: collection
91
        path: src/content/spec
92
        exclude: ["friends.mdx"]    # 友链页是 MDX，不适合结构化编辑
93
        fields:
94
          - name: title
95
            type: string
96
          - name: description
97
            type: string
98
          - name: body
99
            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，一行就还原了这个规则：

1
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 把它作为纯代码文件打开：

1
- name: site-config
2
  label: 站点设置
3
  type: file
4
  path: src/config/siteConfig.ts
5
  format: code

但改错一个逗号构建就挂了，我最后还是把这段删了。主题配置还是在 IDE 里改比较稳。

坑二：中文标题直接当文件名。

filename 里的 {primary} 默认取标题，中文标题会生成中文文件名。所以我给文章集合用了：

1
filename:
2
  template: "{primary}.md"
3
  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，上面那份配置拿走改改就能用。

折腾的意义不就在于此嘛：花一个下午配置好工具，换来以后每一次写作的心流💗。

参考链接：

如何在Sevalla搭建Firefly博客

Tue, 30 Jun 2026 00:00:00 GMT

Step1.注册一个Sevalla账号#

注册连接：Sign up - Sevalla 建议挂代理，不然可能点Sign Up之后一直转圈

注册页面

注册后进入主页，填写银行卡信息，建议使用中信银行或中国银行的VISA

Step2.开启二步验证#

二步验证

点击左下角，选择自己的账号，然后在Authenticator app 选择启用，然后扫描二维码，若没有二步验证的APP，推荐使用1Password或Ente Auth 开启后登录时就不用接收邮箱的验证码了。

Step3. 连接到GitHub#

在下方的Git login & repository

GitHub连接

点Enable，在自己的代码托管平台启用登录和仓库授权。

Step4.建立一个静态网站#

在左边菜单选择Static Sites

然后点Create static site

创建静态网站

选择仓库

在这一步，你需要选择你Fork下来并修改好内容的博客 Auto-deploy自动部署：需要打开，当修改完内容之后每次Commit就会自动部署到平台上。

构建设置

下面的Build Setting改一下具体按下面的参数修改

Node version :22
Build command: pnpm build
Root directory: .
Publish directory: dist 其他的值默认即可。最后配置一下环境变量

Terminal window

1
NODE_VESION=22

点Create static site。

Step5.配置自定义域名#

在Static sites-刚创建的静态网站名-Domains

域名管理

点Add custom domain

添加域名

如果不需要泛域名的证书，就不用勾选Wildcard。然后按提示配置DNS解析就可以了。

Firefly Wiki Link 内部链接示例

Sat, 03 Jan 1970 00:00:00 GMT

Firefly 支持在 Markdown、MDX 文章中使用 Obsidian 风格的 Wiki Link 内部链接。链接目标填写文章的 slug 或文件路径，都不需要包含扩展名，具体匹配规则见下文「链接目标的三种写法」。

文章链接卡片#

[[slug]] 单独成段时，会自动读取目标文章的标题、描述、发布时间、分类、标签和封面，渲染为链接卡片：

1
[[firefly]]
2

3
[[guide/index]]
4

5
[[markdown-extended]]

firefly

Firefly 简单使用指南

如何使用 Firefly 博客模板。

1970-01-02博客指南#Firefly#博客#Markdown#使用指南

markdown-extended

行内链接#

[[slug]] 出现在正文中间时，渲染为普通链接，链接文字自动使用目标文章的标题

1
请参阅 [[firefly]] 了解主题特性。

请参阅 firefly 了解主题特性。

自定义显示标题#

在 | 后填写链接的显示文字。行内链接会用它替换文章标题；单独成段时依然渲染为卡片，卡片标题使用自定义文字，描述、时间、分类、标签和封面仍然读取目标文章：

1
请参阅 [[firefly|主题介绍]] 了解主题特性。
2

3
[[firefly|Firefly 主题介绍]]

请参阅主题介绍了解主题特性。

Firefly 主题介绍

一个例外：如果 | 后的文字只是把链接目标又抄了一遍（[[guide/index|index]]），会被当作无效别名忽略，仍然显示文章标题。Obsidian 在插入的链接时会自动补上这样的别名，避免笔记里显示一长串路径，这个例外就是为它准备的。

链接目标的三种写法#

用 Obsidian 管理文章时，把 src/content/posts 目录本身作为 Obsidian 仓库（vault）打开。下文提到的「仓库根目录」都指这个目录，它正好也是 Firefly 解析链接路径的起点。

链接目标按以下顺序匹配：

写法	示例	在 Obsidian 中
frontmatter 的 `slug`	`[[firefly-wiki-link]]`	✗ 不支持
文件路径（相对仓库根目录）	`[[guide/firefly-layout-system]]`	✓ 需改设置（推荐）
裸文件名（仓库内唯一时）	`[[firefly-layout-system]]`	✓ 默认即是

第一种：slug#

slug 写法在 Obsidian 中不支持，slug 是 Firefly 自己的概念，Obsidian 不读取 frontmatter 里的 slug，所以按 slug 写的链接在 Obsidian 里既不会自动补全，也点不动，只有构建出的站点上能正常跳转。如果你主要在 Obsidian 里写作，用下面两种写法。

第二种：文件路径（推荐）#

文件路径写法需要改 Obsidian 设置，在 设置 → 文件与链接 → 链接 → 内部链接类型 中选择基于仓库根目录的绝对路径，Obsidian 插入的链接才会带上目录：

1
[[guide/firefly-layout-system|firefly-layout-system]]

guide/firefly-layout-system

因为仓库根目录就是 src/content/posts，Obsidian 写出的这个路径和 Firefly 需要的路径完全一致，不需要任何额外转换。

上面这行末尾的 |firefly-layout-system 是 Obsidian 自动补的别名，Firefly 会忽略它，卡片标题仍然取文章的 title，除非你把它修改和文件名不一致，才会变成你修改后的别名。

内部链接类型下拉框里的基于当前笔记的相对路径只在同目录内可用：它给同目录文章生成的是裸文件名，能正常匹配；但跨目录时会生成 ../ 前缀，Firefly 无法解析，链接会按原文显示。

第三种：裸文件名#

「内部链接类型」的默认值就是尽可能简短的形式：只要文件名在整个仓库里唯一，Obsidian 插入的链接就只有文件名，不带目录。这种写法不需要改任何设置，效果和写完整路径完全一致：

1
[[firefly-layout-system]]

firefly-layout-system

文件名重名时这种写法会失效，构建日志里会给出提示，改用完整文件路径即可，所以推荐直接修改 Obsidian 内部链接类型设置为基于仓库根目录的绝对路径，使用第二种文件路径写法，一劳永逸

链接到其他文章的标题#

在文章 slug 后添加 #标题。带标题锚点的链接始终渲染为普通链接：

查看代码块语法高亮

guide/firefly-layout-system#相关链接#相关链接

1
[[code-examples#语法高亮|查看代码块语法高亮]]
2

3
[[guide/firefly-layout-system#相关链接|firefly-layout-system]]

标题锚点使用与页面标题相同的 slug 规则，因此中文、空格和大小写都会按页面实际生成的 ID 处理。

链接到本页标题#

省略文章 slug，只填写标题即可链接到当前文章：

跳转到本页目标

1
[[#本页目标|跳转到本页目标]]

本页目标#

这是本页 Wiki Link 指向的标题。

不支持附件嵌入#

附件嵌入语法目前不会被转换，会按原文显示：

![[image.png]]

行内代码和代码块中的 [[firefly]] 也不会被转换。