CloudCannon 与 Astro

CloudCannon 是一个基于 Git 的无头内容管理系统，为你的内容和 UI 组件提供可视化编辑器，带来丰富的实时编辑体验。

与 Astro 集成

本指南将介绍使用 CloudCannon 网站仪表盘将 CloudCannon 配置为 Astro 的 CMS 的过程。

网站仪表盘为你提供了 Astro 文件的有序视图，以及使用以下方式编辑它们的能力：

用于管理结构化数据文件和 markup 标记的数据编辑器。
一个用于所见即所得的富文本编辑的内容编辑器，采用简洁视图。
一个可视化编辑器，用于交互式预览你的网站，允许你直接在页面上进行编辑。

你还可以为一个极简的源代码编辑器（在浏览器中用于对文件源代码进行微小更改的代码编辑器）配置基于角色的访问权限。

前提条件

一个 CloudCannon 账号。如果你还没有账号，你可以在 CloudCannon 注册。
一个现有的 Astro 项目，存储在本地或存放在 CloudCannon 支持的任一 Git 提供商：GitHub、GitLab 或 Bitbucket。如果你没有现有项目，可以使用 CloudCannon 的 Astro 起始模板开始。

配置新的 CloudCannon 网站

以下步骤将从你的仪表盘配置一个新的 CloudCannon 网站。该网站将连接到现有的 Astro 仓库，然后你可以使用 CloudCannon 的所见即所得文本编辑器来管理和编辑内容。

在你的 CloudCannon 组织首页上，创建一个新网站。
验证你的 Git 提供商并选择要连接的 Astro 仓库。
选择一个你的网站的名字，然后 CloudCannon 会创建该网站并开始同步你的文件。
在网站仪表盘中按照 CloudCannon 的引导任务完成网站初始化设置，包括创建一个 CloudCannon 配置文件（cloudcannon.config.yml）。
通过将配置添加到你的 CloudCannon 配置文件，配置 CloudCannon 在编辑器中的外观和行为。你可以使用 CloudCannon 的配置模式进行编辑，或者在代码编辑器中手动添加配置。
关闭配置模式以返回面向内容创建者的编辑界面。你的配置文件将与其余文件一起保存回你的代码库。

现在你可以在网站仪表盘中浏览，查看 Astro 网站的内容文件，并根据需要使用内容编辑器（例如 .md、.mdx）、数据编辑器（例如 .yml、.json）和可视化编辑器（例如 .astro）进行编辑。

你也可以利用 CloudCannon 的一些功能，例如将文件组织为集合、创建 CloudCannon 模式和将项目设置为可视化编辑。

有关更详细的说明，请参阅 CloudCannon 的入门指南。

CloudCannon 集合与模式

如果你使用 Astro 的内容集合，那么你会熟悉 CloudCannon 的集合概念（用于在网站仪表盘中进行组织/导航）和模式（用于定义新内容条目的格式）。

你的 CloudCannon 网站仪表盘允许你将 Astro 项目的页面和内容组织为集合：具有相似格式的相关文件组。这使你能够将相似类型的内容聚在一起以便于编辑，并使你的内容文件易于导航、排序和筛选。

为集合创建一个 CloudCannon 模式

为确保你的 CloudCannon 条目的数据属性与内容集合中定义的 Zod 验证 schema 匹配，你可以创建一个 CloudCannon 模式（用于创建新条目的空白模板文档）。创建模板模式可以确保在 CloudCannon 中创建的任何新文档都具有你的内容集合所需的属性，从而避免项目中的类型错误。你的 CloudCannon 模式还可以包含用于启动新文档的默认值，例如个人博客的作者姓名。

下面的示例将基于 Astro 内容集合（blog）为使用 Markdown 撰写的博客文章创建一个 CloudCannon 模式。该模式将在从 CloudCannon 的 “Posts” 集合创建新条目时可用：

创建一个 .cloudcannon/schemas/ 文件夹，如果不存在的话。
在此文件夹中添加一个现有的空白文件，作为默认的博客文章模板使用。文件名无关紧要，但该文件必须与你的 Astro 内容集合条目使用相同的文件扩展名（例如 post.md）。
提供内容集合模式所需的必要 frontmatter 字段。你不需要为这些字段提供任何值，但你包含的任何内容在创建新条目时将被自动包含。这些字段将在你的内容编辑器的侧栏中可用。

下面的博客文章示例模式为标题、作者和日期提供了占位符：
.cloudcannon/schemas/post.md
```
---
title:
author:
date:
---
```

在你的 CloudCannon 配置文件的 collections_config 属性中，在 “Posts” 集合下的 CloudCannon 集合下添加你的模式文件路径。

collections_config:
  posts:
    path: content/blog
    name: Posts
    icon: post_add
    schemas:
      default:
        path: .cloudcannon/schemas/post.md
        name: Blog Post Entry

创建新条目

在你的 CloudCannon 网站仪表盘中，你可以使用 “Add” 按钮创建新内容。你可以根据当前所在集合，从你在 cloudcannon.config.yml 中定义的模式中选择条目类型。

你也可以将文件上传到 CloudCannon，或在你的 Astro 项目中直接创建新文件。当你保存网站更改时，在任一位置创建的新文件将被同步，并可在 CloudCannon 和你的 Astro 项目中使用。

以下示例将使用符合 blog Astro 内容集合而创建的 post.md 模板模式，从 CloudCannon 网站仪表盘的 “Posts” 集合中创建一篇新的博客文章：

在 CloudCannon 网站仪表盘中，导航到表示你要添加的内容类型的集合。例如，导航到 “Posts” 集合以添加新的博客文章。
使用 “Add” 按钮创建新文章。如果你已配置 CloudCannon 的 post.md 模式，则可以选择默认的博客文章条目来创建新文章。
在内容编辑器的侧边栏填写必要字段（例如 title、author、date），发布内容并保存你的文章。
文章已保存在本地的 CloudCannon 中，现在应该可以在网站仪表盘的 “Posts” 集合中看到。你可以在该仪表盘页面查看并编辑所有单独的文章。
当你准备将这篇新文章提交回你的 Astro 仓库时，在网站仪表盘的 “网站导航” 侧边栏中选择 “Save”。此操作会显示自上次提交回仓库以来对你网站所做的所有未保存更改，并允许你查看并选择要保存或放弃的更改。
返回查看你的 Astro 项目文件并从 git 拉取新的更改。你现在会在指定目录中找到一个用于该新文章的 .md 文件，例如：
- 文件夹src/
  - 文件夹content/
    文件夹blog/
    my-new-post.md

在你的代码编辑器中导航到该文件，并确认你能看到已输入的 Markdown 内容。例如：

---
title: My New Post
author: Sarah
date: 2025-11-12
---

This is my very first post created in CloudCannon. I am **super** excited!

渲染 CloudCannon 内容

使用 Astro 的内容集合 API 查询并显示你的文章和集合，就像在任何 Astro 项目中那样。

显示集合列表

以下示例显示每篇文章标题的列表，并包含指向各个文章页面的链接。

---
import { getCollection } from 'astro:content';

const posts = await getCollection('blog');
---
<ul>
  {posts.map(post => (
    <li>
      <a href={`/posts/${post.slug}`}>{post.data.title}</a>
    </li>
  ))}
</ul>

显示单个条目

要显示单个文章的内容，你可以导入并使用 <Content /> 组件将内容渲染为 HTML：

---
import { getEntry, render } from 'astro:content';

const entry = await getEntry('blog', 'my-first-post');
const { Content } = await render(entry);
---

<main>
  <h1>{entry.data.title}</h1>
  <p>By: {entry.data.author}</p>
  <Content />
</main>

有关查询、过滤、显示集合内容等更多信息，请参阅完整的内容集合文档。

部署 CloudCannon + Astro

CloudCannon 在其所有计划中都提供免费网页托管（底层使用 Cloudflare）。但是，你也可以使用几乎任何能够从 Git 仓库部署的托管服务提供商进行托管。

要部署你的网站，请访问我们的部署指南并按照你首选托管提供商的说明操作。

配置可视化编辑

CloudCannon 的可视化编辑器让你可以在网站的实时交互预览中查看并编辑文本、图像和其他内容。这些更新可以通过可编辑区域、数据面板和侧边栏进行。

按照 CloudCannon 的指南设置可视化编辑（也可在你的网站仪表盘中找到）。这将向你展示如何通过在 DOM 元素上设置 HTML data- 属性或插入 web 组件来定义实时预览中的可编辑区域。

例如，下面的模板创建了一个可编辑的 author 值，可在实时预览中进行更新：

<p>By: <editable-text data-prop="author">{author}</editable-text></p>

使用组件进行可视化编辑

CloudCannon 允许你为 Visual Editor 中的 Astro 组件定义组件可编辑区域，以便实时重新渲染。这为你的 Astro 组件提供相同的交互式编辑体验。

安装 @cloudcannon/editable-regions 包。
- npm
- pnpm
- Yarn
终端窗口
npm install @cloudcannon/editable-regions
终端窗口
pnpm add @cloudcannon/editable-regions
终端窗口
yarn add @cloudcannon/editable-regions

添加 editableRegions 集成到你的 Astro 配置：

import { defineConfig } from 'astro/config';
import editableRegions from "@cloudcannon/editable-regions/astro-integration";

export default defineConfig({
  // ...
  integrations: [editableRegions()],
  // ...
});

按照 CloudCannon 的说明注册你的组件。这会告诉 CloudCannon 这些组件应打包以便在可视化编辑器中用于客户端。

为组件添加适当的属性以便可视化编辑。例如，以下 CTA.astro 组件的属性（例如 description 和 button color）可以在 CloudCannon 的可视化编辑器中更新：

---
const { description, link, buttonText, buttonColor } = Astro.props;
---

<p data-editable="text" data-prop="description">{description}</p>
<a href={link}>
    <span data-editable="text" data-prop="buttonText" style={`background-color: ${buttonColor}`}>{buttonText}</span>
</a>