2026 年的 Astro + Decap
Source: Dev.to
我终于开始着手一个我思考已久的项目：一个易于维护的摄影和建筑作品集博客。
我借此机会尝试了 Decap，一个基于 Git 的 CMS，我已经想尝试一段时间但一直没有机会。几年前，我在思考做类似项目时发现了它。
我非常喜欢使用 Astro，而在为个人博客写作时，我常常希望有一个可视化界面来降低发布内容的摩擦。我希望我的站点是静态的——我不需要（也不想要）数据库，哪怕是托管的。但我确实想要一个不错的写作界面，而不是 IDE 或 Obsidian，能够更贴合我的博客定制化。
让一切正常运行花的时间比预期稍长，所以我决定写下这篇文章，帮助那些考虑使用相同技术栈的朋友们。
安装 Decap
从文档中我看到有两种安装 Decap 的方式：
- 使用 CDN 版本。
- 使用像
npm这样的包管理器。
我选择了第二种方式，但有点不知所措：然后呢？我该在哪里导入并调用该模块？
关于认证的简短说明
我当时并不在乎认证；我只想要编辑器。这让我觉得在这个领域还有其他解决方案的空间，而且我不想为测试创建实际的远程仓库。我有本地仓库，但不想把它推送到 GitHub 或 GitLab。
所以我在寻找最小化的安装方式，即使这会花更长的时间才能做好。
Source: …
基本结构（使用 Astro）
1. /public 目录下的 config.yml
配置文件必须放在 public 文件夹中，因为我们会使用 Astro 页面作为首页，并且它会引用 public 根目录下的文件。
# when using the default proxy server port
local_backend: true
backend:
name: proxy
proxy_url: "http://localhost:8081/api/v1"
media_folder: "/src/assets/images/uploads"
collections:
- name: posts
folder: /src/pages/blog
label: "Posts"
fields:
- label: Title
name: title
widget: string2. 管理后台路由（/admin）
创建文件 /src/pages/admin.astro：
---
---
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Admin – Decap CMS</title>
</head>
<body>
<script type="module">
import CMS from "decap-cms-app";
CMS.init();
</script>
</body>
</html>说明 – 这段脚本基本上与 Decap 文档中的代码相同。这里提供更多上下文，因为第一次设置时可能会感到困惑。所有信息均取自官方文档和代码仓库。
附加说明
1. 最小化 config.yml
文档列出了许多配置选项（见此处），但缺少一个简洁的入门示例。
与其把 config.yml 放在 /public，你也可以在 HTML 中添加一个 <script> 标签：
<!-- 用于内联配置的示例占位符 -->
<script type="module">
// 这里可以放置内联 Decap 配置
</script>正如 Decap 文档和 Astro 指南所述。我更倾向于使用 public 文件夹的方式，因为它可以将配置集中在一个位置。
2. 本地仓库
我最初尝试了 test-repo 后端；它对快速检查很方便，但完全是临时的，因此不适合真实项目。
使用本地仓库指南（链接）正是我需要的，但它没有明确说明必需的 backend 配置。proxy 配置来自 decap-server 的 README。
3. CMS.registerPreviewTemplate
这行代码出现在 Install Decap CMS 和 Manual initialization 部分。它用于注册自定义预览组件（一个渲染集合数据的 React 组件），但对基本设置并非必需。你可以在需要自定义预览之前安全地省略它。
4. 使用本地仓库运行
在本地运行时需要本地 API，因为 Decap CMS 依赖 Git。目标是避免添加其他类型的存储，这会违背基于 Git 的工作流的初衷。
启动本地代理服务器：
npx decap-server服务器将监听 http://localhost:8081/api/v1（与 config.yml 中的 proxy_url 相匹配）。当 local_backend: true 时，Decap CMS 将与该服务器通信，直接将更改提交到你的本地 Git 仓库。
TL;DR 检查清单
-
添加
config.yml到/public（或通过<script>标签引用它）。 -
创建
/src/pages/admin.astro，其中包含导入并初始化 Decap 的脚本。 -
安装以下包：
npm install decap-cms-app decap-server -
运行本地代理：
npx decap-server -
启动你的 Astro 开发服务器（
npm run dev），并访问/admin。
就这样！现在你已经为你的 Astro 博客拥有了一个最小化、基于 Git 的 CMS，无需任何外部数据库或认证层。准备好后可以随意扩展自定义预览、认证或远程 Git 提供商。祝发布愉快！
运行本地服务器
您可以使用 decap-server 在与开发服务器不同的端口上运行本地服务器：
npx decap-server查看指南 Working with a Local Git Repository 了解详情。
更封装的替代方案
另一种选项——在官方 Astro 文档中的（已归档的）Astro Decap CMS Starter（CMS guide）中使用——是从 CDN 加载 Decap CMS 并从 /public 文件夹提供一个静态 HTML 文件。
从技术角度来看，这种做法运行良好：
- Decap 自身启动，因此 Astro 在构建时几乎不做任何工作。
- 内容管理完全独立于 Astro 的构建过程。
Source: …
更加定制化的版本
如果你读到这里，你会发现我已经做出了一些选择。这是个人偏好问题，但以下是我认为最佳的做法以及我为何偏爱它而不是其他方案。
关键优势
- 基于代码的配置，而不是
config.yml。 - 不会污染
/public文件夹。 - 易于扩展/自定义。
- 隐私优先：基于 Git，但无需暴露凭证。
实现方式
我在 /src/pages/admin 创建了一个管理路由。该页面包含一个最小化的 HTML 文件，具备以下特点：
- 不使用常规布局。
- 仅包含一个加载并配置 Decap CMS 的
<script>标签。 - 将上传的文件存储在
/src/assets，以便 Astro 后续处理。 - 更像是对我常规工作流的自动化，而不是一个独立的系统。
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<title>Astro Admin</title>
</head>
<body>
<script type="module">
import CMS from "decap-cms-app";
const config = {
localBackend: true,
backend: {
name: "proxy",
proxy_url: "http://localhost:8081/api/v1",
},
load_config_file: false,
media_folder: "/src/assets/images/",
collections: [
{
name: "posts",
label: "Posts",
folder: "src/blog",
create: true,
fields: [
{ label: "Title", name: "title", widget: "string" },
{ label: "Body", name: "body", widget: "markdown" },
{ label: "Created", name: "created", widget: "datetime" },
{ label: "Tags", name: "tags", widget: "list" },
],
},
],
};
CMS.init({ config });
</script>
</body>
</html>手动初始化过程请参阅 Customizing Decap CMS → Manual Initialization。window.CMS_MANUAL_INIT = true 已不再需要。
身份验证
我有意暂时不加入身份验证。我并不需要它，且添加不必要的身份验证可能会引入安全漏洞，却没有提供显著的好处。