跳转到内容

内容集合

Content collections 让 Astro 能以结构化方式加载 Markdown、MDX 和数据文件。它不是把内容当成一堆松散文件,而是定义 collection、校验 frontmatter,并通过 Astro 内容 API 查询条目。

当站点超过几个页面后,这一点会变得很重要。标题、描述、日期、标签、草稿状态、来源和关系,不应该完全依靠复制粘贴时的自觉。

当内容有重复形状时,就适合使用 collection:

  • 带日期、作者、标签和摘要的博客文章
  • 带 description 和相关链接的文档页面
  • 带版本号和发布日期的 changelog
  • 带客户、产品、行业字段的 case study
  • 用来生成页面的数据文件

如果只是两三个手写页面,未必需要 collection。但一旦内容需要重复、查询、筛选或生成路由,collection 很快就会变得划算。

一个 blog collection 可以是这样:

src/content/blog/
first-post.md
second-post.md

在 src/content.config.ts 中定义 collection:

import { defineCollection, z } from 'astro:content';
const blog = defineCollection({
schema: z.object({
title: z.string(),
description: z.string(),
publishedAt: z.date(),
tags: z.array(z.string()).default([]),
draft: z.boolean().default(false),
}),
});
export const collections = { blog };

然后写一篇内容:

---
title: "First post"
description: "A short introduction to the site."
publishedAt: 2026-05-23
tags: ["astro", "content"]
---
This is the body of the post.

如果必要字段缺失或类型不对,Astro 可以在开发或构建阶段暴露问题,而不是让不一致的 metadata 进入生产环境。

用 getCollection() 加载条目:

---
import { getCollection } from 'astro:content';
const posts = await getCollection('blog', ({ data }) => !data.draft);
posts.sort((a, b) => b.data.publishedAt.valueOf() - a.data.publishedAt.valueOf());
---
<ul>
{posts.map((post) => (
<li>
<a href={`/blog/${post.id}/`}>{post.data.title}</a>
<p>{post.data.description}</p>
</li>
))}
</ul>

这样索引页就可以由内容 metadata 渲染,而不是手写一组固定链接。

Collection 条目不会自动变成页面。需要一个动态路由把条目转成 URL:

---
import { getCollection, render } from 'astro:content';
export async function getStaticPaths() {
const posts = await getCollection('blog', ({ data }) => !data.draft);
return posts.map((post) => ({
params: { id: post.id },
props: { post },
}));
}
const { post } = Astro.props;
const { Content } = await render(post);
---
<article>
<h1>{post.data.title}</h1>
<p>{post.data.description}</p>
<Content />
</article>

如果这个文件位于 src/pages/blog/[id].astro,每篇条目都会生成 /blog/ 下的页面。

有用的 schema 应该足够严格,能发现错误;但也不要严格到让每次编辑都很痛苦。

字段作用
title页面标题、索引、社交预览
description搜索摘要、卡片、列表页
publishedAt 或 updatedAt排序、时效性、changelog
tagstopic index 和相关内容
draft防止未完成内容发布
canonical处理导入或转载内容
related支持人工整理的阅读路径

对于生成式文档,schema 应该约束公开站点真正会用到的 metadata。不要因为内部研究阶段用过某个字段,就把它带进公开内容模型。

Starlight 使用 Astro content collections 管理 docs 内容。这也是 Starlight 能校验 frontmatter、生成导航、支持搜索和本地化页面的基础。

你仍然可以在 Starlight docs 之外定义额外 collection。例如文档站可以增加 changelog、examples、integrations 或 release notes 集合。

症状检查什么
构建在日期字段失败YAML 日期格式或 schema 类型
页面能渲染但索引页没有它filter 函数排除了 draft 或 tag
动态路由 URL 不符合预期路由使用 id,但想要的是 frontmatter slug
多语言 metadata 不一致schema 把本该必填的字段设成可选
内容模型变得难编辑schema 在建模内部流程,而不是公开内容