Hugo 与 Decap 是怎么接起来的

静态站的内容管理一直有个矛盾：产物是文件，但写内容的人不想碰 Git。 Decap CMS 就是架在这个矛盾中间的一层。它的做法很朴素 —— 把 Markdown 文件当作数据库。

两条链路

一、读：前台渲染

浏览器 → hugo server (1313) → 读 content/ + layouts/ + assets/ → HTML

Hugo 在启动时把 content/posts/*.md 全部解析进内存，改文件立刻重建。 这条链路没有任何 CMS 参与，所以没有 Decap 也能正常出站。

二、写：后台保存

浏览器 /admin/ → decap-server (8081) → 直接写工作区文件 → Hugo 热重载

关键在于 8081 那个进程。它是 Decap 的 proxy backend： 把"提交到 Git"这个动作，降级成"改本地文件"。

映射关系

CMS 和 Hugo 之间靠三处约定对齐，改任何一处都要两边一起改：

# static/admin/config.yml
folder: content/posts                      # ← 对应 Hugo 的内容目录
media_folder: "static/images/uploads"      # ← 上传图片落盘位置
public_folder: "/images/uploads"           # ← 前台引用图片的 URL 前缀

几个容易踩的坑

1. local_backend 忘了开 → 后台会尝试走真实 OAuth，登录页卡住。
2. date 格式和 Hugo 不兼容 → 文章能保存但列表页排序错乱。 用 format: "YYYY-MM-DDTHH:mm:ssZ"，输出 RFC3339，Hugo 认。
3. 只跑 Hugo 没跑 decap-server → 前台正常、后台能打开，但一保存就报网络错误。
4. 中文标题的 slug → slug.encoding 必须是 unicode，否则文件名会被清成空串。

什么时候该换方案

这套组合的边界很清楚：

• 单人 / 小团队写博客：足够，且零成本
• 需要多人协作、审核流：上 publish_mode: editorial_workflow（依赖 Git 远端分支）
• 需要数据库查询、动态渲染：Hugo 就不合适了，换 SSR 框架

一句话总结：Hugo 负责"内容 → 网页"，Decap 负责"人 → 内容"， 两边唯一的耦合面就是 content/ 目录里那堆 Markdown。