示例项目一：MDX 内容站

这是一段占位正文，用于验证项目详情页的排版、锚点与上下篇导航。内容会替换为真实项目复盘。

背景与目标#

示例项目的目标是把内容与表现分离：新增一篇文章只需要新增一个 MDX 文件，页面代码不需要改动，同时保证构建期就能发现字段缺失。

• 内容以文件形式维护，不引入数据库
• 构建期完成校验、排序与代码高亮
• 产物为纯静态目录，可部署到任意静态托管

方案与实现#

整体分成三层：内容读取、渲染管线、页面组装。每一层只承担一种职责，便于替换数据源。

内容读取#

src/lib/content.ts 是对外唯一入口，负责解析 frontmatter、校验字段、过滤草稿并按规则排序。

图片处理#

图片在构建前统一转换为 WebP 与 AVIF，并把尺寸写入 manifest，组件据此写出固定宽高：

const widths = [640, 960, 1280, 1920];
await sharp(file).resize({ width: 960 }).webp({ quality: 78 }).toFile(output);

难点与取舍#

1. 静态导出没有运行时：所有校验与高亮必须在构建期完成，运行时只做渲染。
2. MDX 与 TOC 的 slug 必须一致：否则点击目录无法定位，这里统一使用 github-slugger。
3. 图片无法按需缩放：只能预先输出多档宽度，用 srcset 交给浏览器选择。

取舍原则：构建期能算完的事情不放到浏览器，宁可构建慢一点，也不要让首屏等待。

结果与复盘#

示例项目没有真实指标，这里保持留空。复盘部分记录的是流程上的改进：先固定数据模型，再写页面，能显著减少返工。