Cosmic & Astro

Cosmic 是一个无头 CMS，它提供了一个管理仪表盘来管理内容，以及一个可以与各种前端工具集成的 API。

先决条件

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

将 Cosmic 与 Astro 集成

安装必要的依赖项

添加 Cosmic JavaScript SDK 以从你的 Cosmic Bucket 获取数据。

npm install @cosmicjs/sdk

pnpm add @cosmicjs/sdk

yarn add @cosmicjs/sdk

配置 API 密钥

在你的 Astro 项目的根目录下创建一个 .env 文件（如果尚不存在）。将 Cosmic 仪表盘中可用的 Bucket slug 和 Bucket read key 作为公共环境变量添加进去。

PUBLIC_COSMIC_BUCKET_SLUG=YOUR_BUCKET_SLUG
PUBLIC_COSMIC_READ_KEY=YOUR_READ_KEY

从 Cosmic 获取数据

创建一个名为 cosmic.js 的新文件。将此文件放在项目中的 src/lib 文件夹内。

添加以下代码，以使用 SDK 和你的环境变量从 Cosmic 获取数据。

下面的示例创建了一个名为 getAllPosts() 的函数，用于从 Cosmic 的 posts 对象中获取元数据

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
}

在 Cosmic 文档中阅读更多关于查询的信息。

在 .astro 组件中导入你的查询函数。获取数据后，查询结果可以在你的 Astro 模板中使用。

以下示例展示了从 Cosmic 的 posts 中获取元数据，并将这些值作为 props 传递给 <Card /> 组件，以创建一个博客文章列表

---
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>

查看 Card 组件的源代码

使用 Astro 和 Cosmic 构建博客

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

Cosmic 内容对象

以下说明假定你在 Cosmic 中有一个名为 posts 的对象类型。每篇单独的博客文章都是一个 post，在 Cosmic 仪表盘中通过以下元字段定义：

文本输入 - 作者
图片 - 封面图片
重复器 - 标签
- 文本输入 - 标题
文本区域 - 摘要
富文本 - 内容

在 Astro 中显示博客文章列表

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

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

---
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 生成单篇博客文章

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

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

要从 Cosmic 访问你的数据

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

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

---
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>