土豆不吃鱼
返回 Astro 建站手记

2.1 Markdown 与 frontmatter

阅读 约 2 分钟

内容集合

把同类 Markdown 放进一个目录，在配置文件里声明它，就成了一个「集合」。之后可以按集合取数据：

const posts = await getCollection('posts');

frontmatter 用 schema 约束

文件头两条 --- 之间的部分是 frontmatter。用 schema 声明它之后：

  • 缺字段、类型写错会在构建时报错，而不是等到页面上出现 undefined
  • 编辑器里能补全字段名
const postSchema = z.object({
  title: z.string(),
  date: z.union([z.string(), z.date()]),
  tags: z.array(z.string()).default([]),
});

把 schema 单独放在一个模块里，构建脚本和页面就能共用同一份定义——否则迟早会出现「构建脚本放行、页面渲染报错」这种两套规则不一致的情况。

日期的坑

YAML 里写 date: 2026-09-14（不加引号）会被解析成日期对象，加了引号则是字符串。两种形态混在数据里，排序和格式化就容易出错。

稳妥做法是在产出前统一归一化成固定格式的字符串，让下游只面对一种形态。

排序必须确定

按日期排序时，同一天的文章顺序取决于比较函数的兜底规则。如果只按日期比，相同日期的相对顺序就依赖底层排序的实现和数据传入顺序——不同机器上可能构建出不同的页面顺序。

一定要再加一个稳定的次级排序键（比如标题）。这类问题不会报错，只会让产物难以复现。