Cosmic 与 Astro

Cosmic 是无头 CMS，提供了一个用于管理内容的管理仪表板和一个可以与各种前端工具集成的 API。

¥Cosmic is a headless CMS that provides an admin dashboard to manage content and an API that can integrate with a diverse range of frontend tools.

先决条件

¥Prerequisites

一个 Astro 项目 - 如果你想从一个新的 Astro 项目开始，请阅读安装指南。本指南遵循 Astro 无头 CMS 主题和 Tailwind CSS 的简化版本进行样式。
一个 Cosmic 账户和 Bucket - 如果你没有创建一个免费的宇宙账户。创建账户后，系统将提示你创建一个新的空项目。还有一个简单的 Astro 博客模板可用（这是与 Astro Headless CMS 主题相同的模板）来自动导入本指南中使用的所有内容。
你的 Cosmic API 密钥 - 从你的 Cosmic 仪表板，你需要找到 Bucket slug 和 Bucket read 键才能连接到 Cosmic。

整合 Cosmic 与 Astro

¥Integrating Cosmic with Astro

安装必要的依赖

¥Installing Necessary Dependencies

添加宇宙 JavaScript SDK 以从你的宇宙桶中获取数据。

¥Add the Cosmic JavaScript SDK to fetch data from your Cosmic Bucket.

npm install @cosmicjs/sdk

pnpm add @cosmicjs/sdk

yarn add @cosmicjs/sdk

配置 API 密钥

¥Configuring API Keys

在 Astro 项目的根目录下创建一个 .env 文件（如果该文件尚不存在）。将 Cosmic 仪表板中提供的 Bucket slug 和 Bucket read key 添加为公共环境变量。

¥Create a .env file at the root of your Astro project (if it does not already exist). Add both the Bucket slug and Bucket read key available from your Cosmic dashboard as public environment variables.

PUBLIC_COSMIC_BUCKET_SLUG=YOUR_BUCKET_SLUG
PUBLIC_COSMIC_READ_KEY=YOUR_READ_KEY

从 Cosmic 获取数据

¥Fetching Data from Cosmic

Create a new file called cosmic.js. Place this file inside of the src/lib folder in your project.

Add the following code to fetch data from Cosmic using the SDK and your environment variables.

The example below creates a function called getAllPosts() to fetch metadata from Cosmic posts objects:

import { createBucketClient } from '@cosmicjs/sdk'

const cosmic = createBucketClient({
  bucketSlug: import.meta.env.PUBLIC_COSMIC_BUCKET_SLUG,
  readKey: import.meta.env.PUBLIC_COSMIC_READ_KEY
})

export async function getAllPosts() {
  const data = await cosmic.objects
    .find({
      type: 'posts'
    })
    .props('title,slug,metadata,created_at')
  return data.objects
}

Read more about queries in the Cosmic documentation.

Import your query function in a .astro component. After fetching data, the results from the query can be used in your Astro template.

The following example shows fetching metadata from Cosmic posts and passing these values as props to a <Card /> component to create a list of blog posts:

---
import Card from '../components/Card.astro'
import { getAllPosts } from '../lib/cosmic'

const data = await getAllPosts()
---

<section>
  <ul class="grid gap-8 md:grid-cols-2">
    {
      data.map((post) => (
        <Card
          title={post.title}
          href={post.slug}
          body={post.metadata.excerpt}
          tags={post.metadata.tags.map((tag) => tag)}
        />
      ))
    }
  </ul>
</section>

View source code for the Card component

使用 Astro 和 Cosmic 建立博客

¥Building a Blog with Astro and Cosmic

你可以使用 Cosmic 管理 Astro 博客的内容，并创建 Webhook，以便在更新或添加新内容时自动重新部署你的网站。

¥You can manage your Astro blog’s content using Cosmic and create webhooks to automatically redeploy your website when you update or add new content.

Cosmic 内容对象

¥Cosmic Content Objects

以下说明假设你在 Cosmic 中有一个称为 posts 的对象类型。每篇博客文章都是一个 post，在 Cosmic 仪表板中使用以下元字段定义：

¥The following instructions assume that you have an Object Type in Cosmic called posts. Each individual blog post is a post that is defined in the Cosmic dashboard with the following Metafields:

文本输入 - 作者
图片 - 封面图片
中继器 - 标签
- 文本输入 - 标题
文本区 - 摘录
富文本 - 内容

在 Astro 中显示博客文章列表

¥Displaying a List of Blog Posts in Astro

使用与上面相同的数据获取方法，从脚本文件导入 getAllPosts() 查询并等待数据。此函数提供有关每个 post 的元数据，可以动态显示。

¥Using the same data-fetching method as above, import the getAllPosts() query from your script file and await the data. This function provides metadata about each post which can be displayed dynamically.

下面的示例将这些值传递给 <Card /> 组件以显示格式化的博客文章列表：

¥The example below passes these values to a <Card /> component to display a formatted list of blog posts:

---
import Card from '../components/Card.astro'
import { getAllPosts } from '../lib/cosmic'

const data = await getAllPosts()
---

<section>
  <ul class="grid gap-8 md:grid-cols-2">
    {
      data.map((post) => (
        <Card
          title={post.title}
          href={post.slug}
          body={post.metadata.excerpt}
          tags={post.metadata.tags.map((tag) => tag)}
        />
      ))
    }
  </ul>
</section>

使用 Astro 生成个人博客文章

¥Generating Individual Blog Posts with Astro

要为每篇博客文章生成包含完整内容的单独页面，请在 src/pages/blog/[slug].astro 创建动态路由页面。

¥To generate an individual page with full content for each blog post, create a dynamic routing page at src/pages/blog/[slug].astro.

该页面将导出一个 getStaticPaths() 函数，以在每个 post 对象返回的 slug 处生成页面路由。该函数在构建时调用，并立即生成并渲染你的所有博客文章。

¥This page will export a getStaticPaths() function to generate a page route at the slug returned from each post object. This function is called at build time and generates and renders all of your blog posts at once.

要从 Cosmic 访问你的数据：

¥To access your data from Cosmic:

查询 getStaticPaths() 内部的 Cosmic 以获取有关每个帖子的数据并将其提供给函数。
使用每个 post.slug 作为路由参数，为每个博客文章创建 URL。
返回 Astro.props 内的每个 post，使发布数据可用于页面组件的 HTML 模板部分进行渲染。

下面的 HTML 标记使用来自 Cosmic 的各种数据，例如帖子标题、封面图片和富文本内容（完整博客文章内容）。在显示来自 Cosmic 的富文本内容的元素上使用 set:html，以在页面上渲染与从 Cosmic 获取的 HTML 元素完全相同的 HTML 元素。

¥The HTML markup below uses various data from Cosmic, such as the post title, cover image, and the rich text content (full blog post content). Use set:html on the element displaying the rich text content from Cosmic to render HTML elements on the page exactly as fetched from Cosmic.

---
import { getAllPosts } from '../../lib/cosmic'
import { Image } from 'astro:assets'

export async function getStaticPaths() {
  const data = (await getAllPosts()) || []

  return data.map((post) => {
    return {
      params: { slug: post.slug },
      props: { post }
    }
  })
}

const { post } = Astro.props
---

<article class="mx-auto max-w-screen-md pt-20">
  <section class="border-b pb-8">
    <h1 class="text-4xl font-bold">{post.title}</h1>
    <div class="my-4"></div>
    <span class="text-sm font-semibold">{post.metadata.author?.title}</span>
  </section>
  {
    post.metadata.cover_image && (
      <Image
        src={post.metadata.cover_image.imgix_url}
        format="webp"
        width={1200}
        height={675}
        aspectRatio={16 / 9}
        quality={50}
        alt={`Cover image for the blog ${post.title}`}
        class={'my-12 rounded-md shadow-lg'}
      />
    )
  }
  <div set:html={post.metadata.content} />
</article>

发布你的网站

¥Publishing your site

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

¥To deploy your website, visit the deployment guides and follow the instructions for your preferred hosting provider.

基于 Cosmic 内容更新进行重建

¥Rebuild on Cosmic content updates

你可以直接在 Cosmic 中设置一个 Webhook，以便在更新或添加内容对象时触发在托管平台（例如 Vercel）上重新部署你的网站。

¥You can set up a webhook in Cosmic directly to trigger a redeploy of your site on your hosting platform (e.g. Vercel) whenever you update or add content Objects.

在 “设置” > “webhooks” 下，添加来自 Vercel 的 URL 端点，然后选择你想要触发 Webhook 的对象类型。单击“添加 webhook”以保存它。

¥Under “Settings” > “webhooks”, add the URL endpoint from Vercel and select the Object Type you would like to trigger the webhook. Click “Add webhook” to save it.

Netlify

要在 Netlify 中设置 Webhook：

¥To set up a webhook in Netlify:

Go to your site dashboard and click on Build & deploy.
Under the Continuous Deployment tab, find the Build hooks section and click on Add build hook.
Provide a name for your webhook and select the branch you want to trigger the build on. Click on Save and copy the generated URL.

Vercel

要在 Vercel 中设置 Webhook：

¥To set up a webhook in Vercel:

Go to your project dashboard and click on Settings.
Under the Git tab, find the Deploy Hooks section.
Provide a name for your webhook and the branch you want to trigger the build on. Click Add and copy the generated URL.