New Beginnings：以 id 索引的 Markdown 内容基准测试样本解析

New Beginnings：以 id 索引的 Markdown 内容基准测试样本解析

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby

导读：本文以 Gatsby 仓库中benchmarks/markdown_id基准测试项目的示例博文content/blog/new-beginnings/index.md为切入点，剖析这篇看似“无意义”的 Lorem Ipsum 内容如何在 Gatsby 构建管线中承担查询索引性能基准样本的角色。你将理解：为什么基准项目要用 id 而非 slug 查询页面、Frontmatter 的description字段如何影响 SEO 摘要的生成、以及gatsby-node.js中createPage的 context 如何把id传给模板查询。适合关注 Gatsby 数据层、GraphQL 查询性能与基准测试设计的开发者阅读。

一、样本的定位：它属于哪个基准项目

benchmarks/markdown_id/content/blog/new-beginnings/index.md是 benchmarks/markdown_id 基准项目的三篇示例博文之一。该项目基于gatsby-starter-blog改造，专门用于测量Gatsby 构建大量随机 Markdown 页面时的性能，其核心特点在 README.md 中写得很明确：

“This particular markdown benchmark will query pages by theirid, which is (at the time of writing) faster than indexing pages by theirslug.”

也就是说，这个基准故意选择按id查询页面，因为id索引比按slug索引更快。new-beginnings/index.md正是被纳入该基准的三篇“种子”博文之一，与 hello-world、my-second-post 一同构成站点的初始内容，而真正用于压测的数千篇随机页面则由md.generate.js生成后放置在markdown-pages/目录（该目录由构建脚本生成，仓库中不保留）。

二、逐字段拆解：Frontmatter 的结构与作用

new-beginnings/index.md的 Frontmatter 虽然只有三个字段，却完整覆盖了 Markdown 内容节点被 Gatsby 数据层消费的主要入口：

--- title: New Beginnings date: "2015-05-28T22:40:32.169Z" description: This is a custom description for SEO and Open Graph purposes, rather than the default generated excerpt. Simply add a description field to the frontmatter. ---

2.1 title：页面标题的唯一来源

模板 blog-post.js 中的 GraphQL 查询BlogPostById显式请求了frontmatter.title，并同时用于三处：

• 页面<h1>标题（第 22-30 行）；
• <SEO title={...}>组件（第 18 行）；
• 博客首页列表中通过node.frontmatter.title || node.fields.slug回退显示（src/pages/index.js）。

2.2 date：排序与展示

date字段在 gatsby-node.js 的allMarkdownRemark查询中作为排序键（sort: { fields: [frontmatter___date], order: DESC }），决定博客文章的新旧顺序。同时在模板中用formatString: "MMMM DD, YYYY"格式化为“May 28, 2015”这样的可读形式。注意这里的日期带时区偏移（Z结尾的 ISO 8601 格式），这正是 Gatsby 时间处理的标准输入格式。

2.3 description：自定义 SEO 摘要的示范

description字段的存在极具教学意义。在 src/pages/index.js 中，首页摘要的渲染逻辑是：

node.frontmatter.description || node.excerpt

即：优先使用 Frontmatter 里手写的description，否则回退到gatsby-transformer-remark自动生成的excerpt（默认截断 140 字符）。new-beginnings/index.md的 Frontmatter 特意用整句话描述了这一机制——“This is a custom description for SEO and Open Graph purposes, rather than the default generated excerpt”。这篇样本就是用来演示“自定义描述覆盖自动摘要”这一行为的。

在文章详情模板 blog-post.js 中同样体现：

<SEO title={post.frontmatter.title} description={post.frontmatter.description || post.excerpt} />

由此可以推断：只要在 Frontmatter 里提供description字段，Gatsby 生成的<meta name="description">和 Open Graph 标签就会使用自定义文本；若缺失，则退化为自动摘录。这是 Gatsby 博客 SEO 优化的一个关键约定，也是这篇样本被保留在基准项目中的原因——它同时充当“语法糖文档”。

三、正文的“无用”与“有用”

正文部分是典型的 Lorem Ipsum 风格盲文（placeholder text），包含了丰富的 Markdown 元素，这并非随意为之。从基准测试的角度看，new-beginnings/index.md的正文刻意覆盖了：

• 多级标题（##、###、####、#####、######，第 12-100 行）；
• 无序列表与嵌套列表（第 19-22 行）；
• 有序列表（第 54-58 行）；
• 行内代码与粗体/斜体（第 24-26 行）；
• 引用块（blockquote，第 38-40、66-69 行）；
• 外部链接（第 26、34 行）。

这些元素全部会被gatsby-transformer-remark（配合 gatsby-config.js 中的 remark 插件链：gatsby-remark-images、gatsby-remark-responsive-iframe、gatsby-remark-prismjs、gatsby-remark-copy-linked-files、gatsby-remark-smartypants）转换为 HTML 节点。在构建压测时，这类“结构丰富”的样本可以确保 HTML 生成、AST 解析、代码高亮等链路都被真实地锻炼到，而非只测纯文本。

从阅读者角度看，正文内容本身（关于“word mountains”“blind texts”的虚构故事）没有任何语义信息，它是从 faker 生成随机页面时使用的 Lorem Ipsum 段落保持同构。

四、id 查询链路：从 createPage 到模板

这是本文最核心的源码级部分。按 id 查询的完整链路贯穿三个文件：

4.1 生成 slug 字段

gatsby-node.js 的onCreateNode钩子为每个MarkdownRemark节点生成slug字段：

exports.onCreateNode = ({ node, actions, getNode }) => { const { createNodeField } = actions if (node.internal.type === `MarkdownRemark`) { const value = createFilePath({ node, getNode }) createNodeField({ name: `slug`, node, value }) } }

slug 用于决定页面的 URL 路径，但不是查询的主键。

4.2 createPage 把 id 放入 context

在 gatsby-node.js 的createPages中，每个文章节点被创建为页面，且 context 里同时携带了slug与id：

createPage({ path: post.node.fields.slug, component: blogPost, context: { slug: post.node.fields.slug, id: post.node.id, previous, next, }, })

对比 markdown_slug 基准 的createPage，可以看到后者只传slug不传id。这正是两个基准的核心差异：一个按id查、一个按slug查，从而对比两种索引的构建/查询开销。

4.3 模板按 id 查询

blog-post.js 的 GraphQL 查询接收$id并过滤：

query BlogPostById($id: String!) { markdownRemark(id: { eq: $id }) { id excerpt(pruneLength: 160) html frontmatter { title date(formatString: "MMMM DD, YYYY") description } } }

id是 Gatsby 内部为每个节点分配的唯一标识（由gatsby-source-filesystem创建节点时生成），底层由 Redux 数据层的索引直接定位，不需要像 slug 那样经由createFilePath派生再索引，因此查询更快——这也印证了 README 中“按 id 索引比按 slug 快”的说法。此外，previous/next上下文（第 34-36 行）被模板用于渲染文章底部的前一篇/后一篇导航（第 62-76 行），这是 starter-blog 的标准分页逻辑。

五、如何在本地跑起来

markdown_id基准的可复现步骤如下（摘自 README.md 并补充说明）：

# 1. 安装依赖（建议使用 yarn） yarn # 2. 完整基准：重新生成随机页面 → 清缓存 → 构建 yarn bench # 等价于： # rm -r markdown-pages # NUM_PAGES=2000 node md.generate.js # gatsby clean # node --max_old_space_size=2000 node_modules/.bin/gatsby build # 3. 若不想重新生成页面，只做无再生构建 yarn benchnb

关键参数与脚本细节：

• NUM_PAGES：控制生成的随机页面数量，md.generate.js 中默认值为1000，而 package.json 的bench脚本默认2000。README 中示例使用NUM_PAGES=2000并配合--max_old_space_size=2000提升 Node 内存上限，页面较少时可直接gatsby build。
• MAX_NUM_ROWS：控制每篇随机页面的表格行数上限，默认 25（md.tpl.js）。
• 生成器校验：md.generate.js会对MAX_NUM_ROWS与NUM_PAGES做整数校验（第 8-31 行），非法值直接抛错。
• postinstall钩子会自动清理并重新生成markdown-pages/（package.json），所以克隆后直接yarn即可获得完整压测数据。

需要注意的是：基准站点需要node 8+（README 原话，仓库锁定于gatsby ^2.19.5、react ^16.12.0，见 package.json），与现代 Gatsby v5 的依赖栈不同，若在本仓库根目录统一构建请以各基准目录独立的package.json为准。

六、结论：一篇样本的三重价值

new-beginnings/index.md在基准项目中同时承担三种角色：

1. Frontmatter 语法示范——description字段演示了“自定义 SEO 描述覆盖自动 excerpt”的约定；
2. 结构化内容样本——丰富的 Markdown 元素确保渲染管线被完整覆盖；
3. id 索引基准的最小单元——它与数千篇随机页面一起，被 gatsby-node.js 通过createPage的 context 携带id，再由模板按markdownRemark(id: { eq: $id })查询，共同支撑“按 id 索引快于按 slug 索引”这一基准结论。

因此，读这篇文章时，不要把它当作一篇“博文”，而应把它视为一个可运行的基准测试夹具。当你需要评估 Gatsby 在大规模 Markdown 内容下的构建性能，或想理解 id/slug 两种查询路径的差异时，benchmarks/markdown_id 与它的孪生项目 benchmarks/markdown_slug 是对照实验的最佳起点。

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby