跳到主要内容
Ed. notes

03 内容模型(二):从 Markdown 到 API

长文 · 2026-11-10 · 合集第 4 / 12 篇

  • 构建日志
  • 内容管线
  • Nitro
  • 测试
第 4 / 12 篇 · 查看全部章节 → 当前:03 内容模型(二):从 Markdown 到 API

03 内容模型(二):从 Markdown 到 API

一句话结论:内容管线的核心不是解析 Markdown,而是决定哪些内容可以出现、以什么顺序出现、图片从哪里来;这些规则要写在代码里,不是写在文档里。

它解决什么问题

上一篇定好了 content/ 的目录、slug 和 frontmatter 契约。但文件不会自己变成站点,中间还差一层运行时:

  • 哪些笔记可以发布,哪些还是草稿;
  • 最新笔记按什么顺序排,系列内的顺序要不要反过来;
  • 标签和系列怎么聚合,计数从哪里来;
  • Markdown 怎么渲染,正文里的图片路径怎么处理;
  • 文章不存在时返回什么,图片被猜到路径时会不会泄露文件。

这些问题看起来零碎,但每一个都可能让内容出错:草稿被 API 带出去、同一日期的笔记顺序每次不一样、系列里的文章倒着排、图片路径能跳出笔记目录。它们不会在 TypeScript 编译时报错,只会在上线后以很隐蔽的方式出现。

所以我把内容管线当成一个独立模块来做:server/utils/content.ts 负责读取、校验、过滤和聚合,Nitro 路由只负责把结果包成 JSON。规则写在函数里,测试覆盖边界,而不是靠「我记得要过滤草稿」。

我怎么试的

1. 两个加载函数,把「校验」和「发布」分开

export const loadAllNotes = (options: LoadContentOptions): ContentNote[] => {
  // 读取全部笔记,包含草稿;任何校验错误都会抛 ContentValidationError
}

export const loadNotes = (options: LoadContentOptions): ContentNote[] => {
  const notes = loadAllNotes(options)
  if (options.includeDrafts) return notes
  return notes.filter((note) => !note.draft)
}

loadAllNotes 给校验脚本用,草稿也要检查;loadNotes 给公开接口用,默认剔除 draft: true。两个函数分开,是为了避免「预览时想看草稿」和「发布时不能带草稿」互相打架。

摘要对象会再把 body 和 draft 去掉:

export const toNoteSummary = (note: ContentNote): NoteSummary => ({
  slug: note.slug,
  title: note.title,
  summary: note.summary,
  type: note.type,
  date: note.date,
  tags: note.tags,
  series: note.series,
  repo: note.repo,
  website: note.website,
})

列表页不需要正文,也不应该知道草稿字段。少传一点,少一点泄露面。

2. 排序:日期倒序,slug 兜底

const byDateDescending = (first: ContentNote, second: ContentNote): number => {
  if (first.date !== second.date) return first.date < second.date ? 1 : -1
  return first.slug.localeCompare(second.slug)
}

日期是 YYYY-MM-DD 字符串,可以直接做字典序比较;同一天再用 slug 兜底,保证每次构建的顺序一致。没有这个兜底,同一天的两篇笔记可能因为文件系统返回顺序不同而换位置,RSS 和分页都会跟着抖。

系列内则是升序:

notes: groupedNotes.sort((first, second) => {
  if (first.date !== second.date) return first.date < second.date ? -1 : 1
  return first.slug.localeCompare(second.slug)
})

最新笔记要倒序,构建日志要正序,两个场景不该共用一个排序函数。

3. 标签和系列:从摘要聚合,不从正文猜

export const aggregateTags = (notes: NoteSummary[]): TagAggregate[] => {
  const counts = new Map<string, number>()

  for (const note of notes) {
    for (const tag of note.tags) {
      counts.set(tag, (counts.get(tag) ?? 0) + 1)
    }
  }

  return [...counts.entries()]
    .map(([name, count]) => ({ name, count }))
    .sort(
      (first, second) =>
        second.count - first.count || first.name.localeCompare(second.name, 'zh-CN'),
    )
}

标签按出现次数降序,次数相同按名称排序。系列则按文件夹名分组,系列之间按文件夹名升序(01- → 06-),组内按阅读序号升序,00-目录.md 因此排在系列第一位。两者都只吃 NoteSummary,不碰正文,所以草稿一旦被过滤掉,聚合结果里也不会出现它的标签和系列。

4. 两条 API:列表和详情

列表接口一次返回三样东西:

export default defineEventHandler(() => {
  const contentDir = String(useRuntimeConfig().contentDir)
  const notes = loadNotes({ contentDir })
  const summaries = notes.map(toNoteSummary)

  return {
    notes: summaries,
    tags: aggregateTags(summaries),
    series: aggregateSeries(summaries),
  }
})

详情接口按 slug 找笔记,找不到就 404:

const note = loadNotes({ contentDir: String(useRuntimeConfig().contentDir) }).find(
  (item) => item.slug === slug,
)

if (!note) throw createError({ statusCode: 404, statusMessage: '笔记不存在' })

const { html, headings } = renderMarkdown(note)

return {
  note: {
    ...toNoteSummary(note),
    html,
    headings,
  },
}

这里有一个容易犯的错:详情接口也必须用 loadNotes,不能用 loadAllNotes。否则只要知道草稿的 slug,就能直接读到未发布内容。草稿过滤不是列表页的装饰,是接口层的边界。

renderMarkdown() 返回 HTML 和标题锚点两个值。锚点来自正文里的二、三级标题,文章页右侧的「本文目录」直接用它;渲染器只负责生成可跳转的 id,不加工作者写的章节序号。

5. 图片:改写路径,而不是相信路径

正文里的相对图片路径会被改写成站点地址:

return `/content-assets/notes/${slug}/${normalized
  .split('/')
  .map((segment) => encodeURIComponent(segment))
  .join('/')}`

改写前会拒绝 ..、反斜杠和空路径,避免 ../../../etc/passwd 这类输入;外部 URL 和以 / 开头的站点绝对路径则原样保留。真正的文件读取在 content-assets 路由里,还要再过三道检查:

if (assetPath !== noteDir && !assetPath.startsWith(noteDir + sep)) throw notFound()
if (!existsSync(assetPath) || !statSync(assetPath).isFile()) throw notFound()
if (!CONTENT_TYPES[extname(assetPath).toLowerCase()]) throw notFound()

第一道防目录穿越,第二道确认文件存在,第三道只允许图片扩展名。路由还会先检查 slug 是否属于已发布笔记,所以草稿目录里的图片也不会被直接访问。

响应头也分环境:

setHeader(
  event,
  'Cache-Control',
  import.meta.dev ? 'no-cache' : 'public, max-age=31536000, immutable',
)

生产环境把图片当成长期缓存资源,缓存一年。代价是:如果同一路径的图片被替换,浏览器和 CDN 不会自动失效。后面要么给文件名加 hash,要么接受「换图就换文件名」。

6. Markdown 渲染:默认不相信 HTML

const markdown = new MarkdownIt({
  html: false,
  linkify: true,
})

html: false 意味着正文里的原始 HTML 不会被渲染;linkify: true 让裸 URL 自动变成链接。图片渲染器会补上 loading="lazy" 和 decoding="async",避免长文里的图片阻塞首屏。

7. 用测试把边界固定下来

内容相关的测试目前有 27 个,覆盖加载、校验、草稿过滤、标签与系列聚合、构建脚本退出码、图片路径改写和目录穿越:

$ npx vitest run tests/nuxt/content.spec.ts

 Test Files  1 passed (1)
      Tests  27 passed (27)

全量测试是 110 个,全部通过。测试用临时目录造内容,不依赖仓库里真实的 content/notes/;这样即使内容目录是空的,管线本身也是被验证过的。

坑和限制

1. 草稿泄露只需要一次手滑。 公开接口误用 loadAllNotes,草稿就会出现在列表或详情里。测试里专门有一条断言「默认排除草稿」,但代码审查时仍然要盯住这个函数名。

2. 排序的稳定性靠约定。 日期相同必须用 slug 兜底,否则顺序会随文件系统变化。这个规则不写下来,下一个人(或者三个月后的我)很容易漏掉。

3. 标签没有规范化。 AI、ai、人工智能 现在是三个标签。聚合函数只负责计数,不负责合并同义词;等内容多起来,需要加白名单或归一化规则。

4. 图片缓存是「永久」的。 immutable 的前提是路径不变、内容不变。如果以后支持在后台替换封面图,就要加文件名 hash 或版本号,否则用户会一直看到旧图。

5. Markdown 的 HTML 是关掉的。 这挡住了 XSS,也挡住了 iframe、自定义组件和复杂嵌入。需要时应该加受控的 shortcode,而不是直接放开 html: true。

6. 内容目录必须进镜像。 前端运行时直接读 content/,部署时它必须被复制进镜像或挂载进容器;默认路径是仓库根 content/,可以用 NUXT_CONTENT_DIR 覆盖。这一点在写 Dockerfile 时还要再验证一次。

7. RSS 和 sitemap 还没接。 数据层已经保证草稿不会进入聚合结果,但 RSS、sitemap 和页面还没实现,所以「草稿不出现在生产」目前只在单元测试层面成立,等页面接上还要再验一遍。

8. 真实内容是空的。 写这一篇时 content/notes/ 还是空的,测试用的是临时目录。管线先于内容是我刻意选的顺序,但真正的考验是第一批 6-8 篇笔记写进来之后,schema 和写作流程会不会互相打架。现在笔记已经有 8 篇,这一关算是过了第一轮。

适合谁

如果你也在做一个 Git 驱动的内容站,想让内容和代码同仓库,又不想引入数据库,这套管线可以直接借鉴:一个 loader、一层 Zod 校验、两条 API、一个受控的图片路由,够用到内容规模很大之前。

如果你以后打算在同一份内容上做 RAG 或站内搜索,这层结构也有用:loadNotes 输出的就是干净的、已过滤的摘要和正文,Agent 不需要再理解你的目录约定。

它不太适合这几类人:用 CMS 或托管博客的人,这些能力平台已经给了;作者不是开发者、需要可视化编辑的团队;以及内容规模大到需要全文索引、权限和审核流的场景。

下一篇写 04 前端:Nuxt + SCSS 的页面实现。内容管线已经把数据准备好了,接下来要把它变成首页、目录、详情和关于四个页面,并在 1440 / 1024 / 768 / 390 四个宽度上验证。

继续探索