Astro v5 中 Content Collections 的正确使用姿势

· ··· ·
#Astro #SSG #TypeScript #Content Collections

问题背景

在实际使用 Astro v5 的 Content Collections 时，很多开发者会遇到以下困惑：

  1. 如何正确定义复杂的 Zod Schema？
  2. getStaticPaths 和 getCollection 的协作关系？
  3. 如何优雅地处理跨集合查询？

本文将结合实例逐一解答。

Content Collections 架构

graph LR
    A[Markdown 文件] --> B[config.ts Zod Schema]
    B --> C[getCollection API]
    C --> D[页面路由]
    D --> E[静态 HTML 输出]

正确定义 Schema

Astro v5 使用 Zod 进行 Schema 定义，推荐将共用字段抽取为基类：

import { defineCollection, z } from 'astro:content';

const baseSchema = z.object({
  title: z.string(),
  description: z.string(),
  pubDate: z.coerce.date(),
  tags: z.array(z.string()).default([]),
  draft: z.boolean().default(false),
});

const blogCollection = defineCollection({
  type: 'content',
  schema: baseSchema,
});

动态路由模式

sequenceDiagram
    participant Build as Astro Build
    participant GetStatic as getStaticPaths
    participant GetColl as getCollection
    participant Page as Page Component
    
    Build->>GetStatic: 请求路径列表
    GetStatic->>GetColl: 获取所有文章
    GetColl-->>GetStatic: 返回文章列表
    GetStatic-->>Build: 返回路径参数
    Build->>Page: 渲染每个页面
    Page-->>Build: 生成 HTML

跨集合查询技巧

当需要在首页展示多个板块的最新文章时，Astro 支持在 getCollection 中传入多个集合名：

// 一次获取多个集合的文章
const posts = await getCollection('blog', 'tutorials', 'notes');

// 然后统一过滤和排序
const published = posts
  .filter(p => !p.data.draft)
  .sort((a, b) => b.data.pubDate.getTime() - a.data.pubDate.getTime());

常见陷阱

  1. 日期格式：使用 z.coerce.date() 而非 z.date()，因为 frontmatter 中的日期会被 YAML 解析为字符串
  2. draft 过滤：记得在静态路径中也过滤 draft 文章，否则它们仍会被构建
  3. 类型推导：Astro v5 的 Content Layer API 提供了更好的类型推导，建议查阅最新文档

总结

Astro v5 的 Content Collections 提供了类型安全且高效的内容管理方式。掌握 Schema 设计、动态路由和跨集合查询后，你可以轻松管理数十个板块、数百篇文章，而保持零维护成本。