跳到主要内容

静态站点的 MDX 内容管线怎么搭

占位示例文章，梳理构建期解析、校验与高亮的完整链路，以及常见的踩坑点。

更新于 2026 年 10 月 14 日阅读约 2 分钟
目录（6 节）

这是一篇占位示例文章，用来验证标题、列表、表格、引用、代码块与图片的渲染效果，内容会在正式发布前替换。

为什么把解析放在构建期

静态站点没有服务端运行时，浏览器每多解析一次 Markdown，就多一次首屏等待。把解析、校验与高亮全部前置到构建期，运行时只剩下渲染 HTML。

  • 首屏不加载 Markdown 解析器
  • 字段错误在构建时报出文件名与字段路径
  • 代码高亮结果直接写进 HTML

读取与校验的顺序

先读文件、再解析 frontmatter、最后交给 schema。顺序反了会让错误信息丢失上下文。

ts
const raw = fs.readFileSync(fullPath, 'utf8');
const { data, content } = matter(raw);
const parsed = postFrontmatterSchema.safeParse(data);
 
if (!parsed.success) {
  throw new Error(`${fullPath} frontmatter 校验失败`);
}

三处容易踩的坑

  1. slug 与文件名不一致：URL 由文件名决定，frontmatter 里的 slug 只用于校验，不一致必须直接失败。
  2. TOC 与标题锚点算法不同：一边用自定义规则，一边用 rehype-slug，点击目录就会跳不到位置。
  3. 草稿泄漏：列表、sitemap 与构建产物必须共用同一个过滤函数，不能各自读目录。

原则：内容错误让构建失败，而不是生成一个缺字段的页面。

性能对照

下面的数字是占位示例，仅用于验证表格样式，不代表真实测量结果。

方案运行时开销构建耗时备注
客户端解析高低首屏需要额外脚本
构建期解析低中推荐
预渲染 HTML最低高内容更新需重建

图片与尺寸

静态导出关闭了框架的图片优化，尺寸必须由构建脚本写入 manifest：

示例配图

组件读取 manifest 后写出 width 与 height，图片未加载时也不会引起布局偏移。

小结

管线的价值不在代码量，而在约束：字段必须校验、排序必须确定、草稿必须过滤。把这些约束固定在 lib/content.ts 一处，页面就只需要关心展示。