一、为什么选 Sveltia 而不是自己写后台#

先说清楚我不想干什么：

我要的是：一个纯前端、零后端、直接调用 GitHub API 的 CMS。GitHub 就是数据库，commit 就是历史，PR 就是预览。

Sveltia CMS（Decap CMS 的活跃 fork）正好干这个。它是一个单文件 JS，加载就跑，所有读写都走 GitHub API。

二、挂进站点：它只是一个静态文件#

CMS 不需要单独部署，把它当普通文件丢进 public/admin/：

1
<!doctype html>
2
<html lang="en">
3
  <head>
4
    <meta charset="UTF-8" />
5
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
    <meta name="robots" content="noindex" />
7
    <title>Blog Admin</title>
8
  </head>
9
  <body>
10
    <script src="https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js"></script>
11
  </body>
12
</html>

就这些。Cloudflare 构建时把它原样拷到 dist/admin/index.html，于是：

1
https://ycxdev.com/admin/         →  CMS

meta robots: noindex 别忘了 —— 否则搜索引擎会收录你的后台。

三、配置：告诉它写到哪去#

public/admin/config.yml（这是我博客的真实配置）：

1
backend:
2
  name: github
3
  repo: devycx/MyBlog
4
  branch: main
5
  base_url: https://sveltia-cms-auth.<你的-workers-子域>.workers.dev
6

7
site_url: https://ycxdev.com
8

9
# 顶层媒体目录（供资源库 / Asset Library 使用）
10
media_folder: src/content/posts/images
11
public_folder: /src/content/posts/images
12

13
collections:
14
  - name: posts
15
    label: Posts
16
    folder: src/content/posts
17
    media_folder: images        # ← 集合级，相对路径
18
    public_folder: images       # ← 集合级，相对路径
19
    create: true
20
    slug: "{{slug}}"
21
    extension: md
22
    summary: "{{title}} - {{published}}"
23
    fields:
24
      - { name: title, label: Title, widget: string }
25
      - name: published
26
        label: Published
27
        widget: datetime
28
        date_format: "YYYY-MM-DD"
29
        time_format: false
30
        format: "YYYY-MM-DD"
31
      - { name: description, label: Description, widget: text, required: false }
32
      - { name: image, label: Cover Image, widget: image, required: false }
33
      - { name: tags, label: Tags, widget: list, required: false, default: [] }
34
      - { name: category, label: Category, widget: string, required: false }
35
      - { name: draft, label: Draft, widget: boolean, default: false }
36
      - { name: body, label: Body, widget: markdown }

folder: src/content/posts 正好是 Astro content collection 的目录。所以：

1
CMS 保存  →  GitHub 上多一个 .md 文件
2
Astro 构建 →  读同一个目录 → 生成一个页面

中间没有任何转换层。 这是整套设计最舒服的地方。

NOTE

那个 draft 开关是真的有用的。站点里过滤草稿的逻辑就一行：

1
getCollection("posts", ({ data }) =>
2
  import.meta.env.PROD ? data.draft !== true : true
3
);

PROD 下过滤草稿，本地 dev 时不过滤。所以草稿能在本地预览、发出去也不会上线 —— 我现在手上这批文章就全是 draft: false 状态。

四、OAuth 中转 Worker：为什么必须搞一个#

GitHub backend 需要 OAuth 登录。麻烦在于 GitHub OAuth App 的 callback URL 是注册时写死的绝对地址，而你现在是通过 https://ycxdev.com/admin/ 访问的。

回调被 GitHub 打到一个不是 CMS 的 URL，Sveltia 拿不到 code，整个流程断掉。

解决办法是插一个 Worker 在中间：

Worker 的职责就三件事：

1
1. 提供一个固定的、已注册的 callback URL
2
2. 完成 code → token 的交换（这一步必须在服务端做，
3
   因为要把 client_secret 藏起来）
4
3. 把 token 安全地交回浏览器

WARNING

Worker 必须持有 client_secret 并在服务端完成 code 交换。 如果把 secret 放进 config.yml，那等于公开了这个 OAuth App —— 任何人拿到 secret 就能冒充你的应用换 token。

这个 Worker 跑在 Cloudflare Workers 免费额度里（10 万请求/天），完全够用。命名上我用的是 sveltia-cms-auth-<Pages 项目名>，和站点同名，纯粹为了好记 —— 你随便起，只要和 GitHub OAuth App 里登记的 callback URL 一致就行。

五、保存一篇文章的完整时序#

现在把 OAuth 之后的部分补完 —— 这是”反向同步”的核心：

几个关键理解：

1. 乐观锁靠 sha。 GitHub 的 contents API 要求更新文件时带上当前的 blob sha。不带就报 422。这样两台设备同时编辑同一篇时会明确冲突，而不是静默覆盖。

2. 图片进仓库，不是图床。 CMS 上传图片走的是 POST /repos/.../contents/<path>，落到 src/content/posts/images/。这正好和我的约定一致 —— 内容以仓库为唯一来源，构建产物可随时重建。

CAUTION

图片进仓库的代价是仓库体积不可逆地增长。GitHub 单文件 100MB、仓库建议 <1GB。放原图的话几十篇文章就能顶满。正确做法是上传前压缩（WebP / AVIF，或长边限制在 1600px）。

3. public_folder 的相对/绝对是个真坑。 见下节。

六、卡了我两天的那个坑#

当时上传的封面图全都 404。文章在 src/content/posts/，frontmatter 里写的是 images/xxx.jpg，Fuwari 主题里是这样解析的：

1
<ImageWrapper src={entry.data.image}
2
              basePath={path.join("content/posts/", getDir(entry.id))} />

也就是说它把 images/xxx.jpg 拼成 content/posts/<目录>/images/xxx.jpg，然后通过 Astro 的图片管线去引用。

但问题是：如果 frontmatter 里写的是 /images/xxx.jpg（带前导斜杠），Astro 会当成 public 目录下的资源去找，当然找不到。

所以关键是 config.yml 里 集合级的 media_folder / public_folder 要用相对路径：

1
# ❌ 顶层用绝对路径 → frontmatter 被写成 /src/content/posts/images/xxx.jpg
2
media_folder: src/content/posts/images
3
public_folder: /src/content/posts/images
4

5
# ✅ 集合级用相对路径 → frontmatter 被写成 images/xxx.jpg
6
collections:
7
  - name: posts
8
    media_folder: images
9
    public_folder: images

WARNING

顺便提醒一个 API 名字的坑：Sveltia / Decap CMS 里这个选项叫 public_folder，不是 public_path。写错了不报错，只是 frontmatter 里路径不对，然后你在主题里死活找不到文件 —— 我就是在这上面浪费了一个下午。

我在 config.yml 里直接把原因写成注释了，因为半年后我一定会忘：

1
# 集合级【相对路径】是关键：
2
#   media_folder: images  -> 图片实际存到 src/content/posts/images/
3
#   public_folder: images -> frontmatter 写成相对路径 images/xxx.jpg

七、这套方案的边界#

说优点也要说缺点，不然是软文。

优点

• 零后端成本，CMS 就是一个静态文件
• 内容、代码、历史全在一个仓库里，git log 就是写作历史
• CMS 挂了不影响发布（git push 照样能上线）
• 换静态托管只需要换部署配置，内容文件一个字不用改

局限

• 写长文体验一般。 Markdown 编辑器就是个文本框，没有大纲导航、没有实时预览、没有类似 Typora 的所见即所得。写代码文章够用，写散文就一般。
• 依赖第三方 CDN。 unpkg.com 挂了后台就白屏。可以自己 host 一份 sveltia-cms.js 到 public/admin/，我暂时没这么做。
• 鉴权粒度粗。 一个 GitHub PAT/OAuth 就是全部权限。多人协作得靠 GitHub 仓库权限管。
• 不是移动端优先。 手机上写长文体验很差。

TIP

我的实际用法是混合的：长文用编辑器/AI 写好 Markdown，push 上去；短文、需要图和快速发布的用 CMS。 CMS 的价值不是”取代编辑器”，是”把发布这一步的摩擦降到零”。

小结#

• CMS 跟着静态站点一起部署，一个 index.html + 一个 config.yml 就完事
• 写入目标是 GitHub 仓库，靠 folder 直接对上 Astro 的 content collection，中间零转换
• OAuth 中转 Worker 解决 callback URL 固定的问题，并且必须把 client_secret 留在服务端
• 每次保存 = 一个 commit = 一次 Pages 重新构建，这就是”反向同步”的全部含义
• public_folder 必须是集合级相对路径，顶层绝对路径会让图片 404
• 图片进仓库，记得压缩，仓库体积不可逆

整个系统的本质就一句话：GitHub 是数据库，commit 是历史，CMS 是个前端，Pages 是个编译器。 四个组件各司其职，谁都不是数据库，但组合起来就是一个完整的 CMS。