Gatsby分页实战：构建时静态分页原理与pageContext避坑指南

1. 项目概述为什么在 Gatsby 里做分页不是“加个组件”那么简单你刚用 Gatsby 搭好一个博客写了二十篇技术笔记首页一刷全堆出来——页面加载慢、首屏白屏时间长、用户划到底都找不到“下一页”按钮。这时候你搜“Gatsby 分页”第一条就是gatsby-awesome-pagination文档写着“一行代码搞定”你兴冲冲 npm install照着示例贴了三行代码结果 build 报错pageContext is not defined再查发现createPages里没传上下文补上之后点击第二页又 404最后翻到 GitHub issues满屏都是“pageContext丢失”“path不匹配”“gatsby-node.js配置后首页不渲染”的抱怨。这不是你代码写错了而是 Gatsby 的分页根本就不是传统框架里“前端切页”的逻辑——它是在构建时build time把每一页都预生成成独立的 HTML 文件而gatsby-awesome-pagination只是帮你自动化这个“批量创建静态页”的过程。它不处理数据来源不决定分页粒度不校验路径规则更不会替你把当前页码塞进 GraphQL 查询变量里。换句话说它是个精密但冷酷的“流水线调度器”你得先搭好原料车间数据层、设定好模具规格分页参数、校准好传送带位置路径与上下文它才肯开工。我去年重构三个 Gatsby 站点的分页系统踩过所有典型坑从createPages中context对象漏传导致所有分页页 404到pageContext在模板中被意外覆盖引发无限重定向再到gatsby-awesome-pagination默认的path拼接规则和中文路径冲突导致 SEO 友好性归零。这篇文章不讲 API 列表只讲你真正上线前必须亲手验证的七道关卡数据怎么切、页码怎么传、路径怎么定、上下文怎么保、模板怎么接、SEO 怎么稳、错误怎么查。如果你正卡在createPages报错、分页链接跳转 404 或者第二页内容和第一页一模一样那你不是缺教程是缺一份按生产环境逐行调试过的操作手册。2. 核心设计逻辑理解 Gatsby 分页的本质与 gatsby-awesome-pagination 的真实角色2.1 Gatsby 分页不是“前端交互”而是“构建时静态页批量生成”很多刚从 Next.js 或 VuePress 转来的开发者第一反应是“加个分页组件点击触发setState切数据”。这在 Gatsby 里完全行不通。Gatsby 的核心哲学是Build-time Static Generation—— 所有页面必须在gatsby build这一步就生成完毕部署后服务器只返回纯 HTML没有运行时数据请求。这意味着不存在“点击下一页 → 发起 GraphQL 请求 → 渲染新内容”这种流程所有分页页如/blog/page/2/、/blog/page/3/都必须在构建阶段由gatsby-node.js中的createPagesAPI 显式创建为独立页面节点每个分页页的pageContext必须包含该页所需的所有参数如currentPage、limit、skip、totalPages这些参数会注入到对应模板组件的props.pageContext中模板组件如blog-list.js在构建时就被编译它接收pageContext后通过useStaticQuery或graphql查询语句注意是编译期查询非运行时获取本页应显示的数据子集。提示你可以把 Gatsby 分页想象成印刷厂印书——gatsby-awesome-pagination是自动装订机但它不负责写文章数据源、不决定每章多少页分页逻辑、不设计封面模板它只按你给的“章节清单”分页配置和“纸张规格”路径规则把已写好的内容GraphQL 查询结果批量裁切成指定页数并装订成册生成/page/2/index.html。你漏掉任何一道前置工序装订机就会卡死或装错。2.2 gatsby-awesome-pagination 的真实定位一个高阶 createPages 封装工具gatsby-awesome-pagination的源码只有不到 200 行它的核心价值不是提供炫酷 UI而是解决createPages中重复性最高的三类问题分页计算自动化根据总条目数totalCount和每页条数limit自动算出totalPages、currentPage、skip值避免手写Math.ceil(totalCount / limit)出错路径生成标准化统一处理/page/:num/、/blog/:num/等常见路径格式支持自定义pathPrefix和pathSuffix防止手拼字符串导致路径不一致上下文注入规范化确保每个分页页的context对象结构统一包含currentPage、limit、skip、totalPages、previousPagePath、nextPagePath等关键字段且类型安全如currentPage强制为数字而非字符串。但它绝不做以下事❌ 不读取或操作你的 GraphQL 数据源allMarkdownRemark、allMdx等❌ 不修改你的 GraphQL 查询语句你仍需在模板中手动写skip和limit参数❌ 不处理pageContext在模板中的使用逻辑你仍需在blog-list.js中正确解构pageContext并传入查询❌ 不兼容 Gatsby v5 的createPagesEphemeral新 API截至 2024 年中它仍基于createPages。我实测过直接手写createPages分页逻辑12 行代码搞定基础分页但加上边界处理首页不显示previousPagePath、末页不显示nextPagePath、路径容错/page/01/和/page/1/统一、SEO 字段注入canonicalURL代码膨胀到 47 行且极易出错。gatsby-awesome-pagination把这部分稳定逻辑封装起来让你专注在业务层——比如“如何让第一页显示 10 篇后续页显示 8 篇”这种真实需求。2.3 为什么 pageContext 是整个链条的“命门”它的生命周期与常见陷阱pageContext是 Gatsby 分页中唯一贯穿构建全流程的“数据信使”它的完整生命周期如下阶段操作者关键动作常见错误1. 构建准备你在gatsby-node.js中调用createPage({ path, component, context: { currentPage: 1, limit: 10, skip: 0 } })漏传context对象或context里缺少currentPage字段 → 后续模板无法获取页码2. 页面创建Gatsby 内核将context序列化并注入到该页面的page-data.json中context包含函数或未序列化对象如Date实例→ build 失败3. 模板渲染你的blog-list.js组件通过props.pageContext.currentPage读取值并用于 GraphQL 查询变量在useStaticQuery中误用pageContextuseStaticQuery无参数不能动态传变量→ 查询结果始终是第一页4. 客户端导航Gatsby Link 组件点击/page/2/时从page-data.json中反序列化pageContext并传入组件path配置错误导致page-data.json404 → 页面白屏控制台报Cannot read property currentPage of undefined最致命的陷阱是pageContext类型错乱。gatsby-awesome-pagination默认生成的currentPage是数字类型但如果你在createPages中手动拼接路径如path:/blog/page/${i}/i是循环索引而i是字符串1那么pageContext.currentPage就是字符串1。当你的 GraphQL 查询写成skip: ${pageContext.currentPage * pageContext.limit - pageContext.limit}时字符串1 * 10结果是10隐式转换但1 - 10却是NaN我曾因此调试了 3 小时最终发现是pageContext.currentPage被意外转成了字符串。解决方案永远只有一条在createPages中显式转换parseInt(i, 10)并在模板中用typeof pageContext.currentPage number做断言。3. 实操全流程从零搭建可上线的 Gatsby 分页系统含完整代码与避坑注释3.1 前置准备确认数据源结构与分页策略在动代码前先明确两个硬性前提第一你的数据源必须支持分页查询。Gatsby 的 GraphQL 层要求数据节点Node具备id字段且全局唯一。以最常见的 Markdown 博客为例确保gatsby-transformer-remark插件已启用且你的 Markdown 文件有正确的 frontmatter--- title: Gatsby 分页实战详解 date: 2024-05-20 slug: /blog/gatsby-pagination --- 正文内容...运行gatsby develop打开http://localhost:8000/__graphql执行以下查询验证数据可用性query { allMarkdownRemark( sort: { fields: [frontmatter___date], order: DESC } limit: 10 skip: 0 ) { totalCount edges { node { id frontmatter { title date } fields { slug } } } } }✅ 成功返回totalCount 0且edges有数据说明数据源就绪。❌ 若totalCount为 0请检查gatsby-source-filesystem的path是否指向正确的 Markdown 目录或gatsby-transformer-remark是否启用。第二确定分页策略——这是影响用户体验的核心决策。不要默认用 “每页 10 篇”。根据你的内容类型选择场景推荐每页条数理由我的实际案例技术博客长文为主6–8 篇首屏加载快避免用户滑动过久单篇文章平均阅读时长 5 分钟用户更倾向深度阅读单篇我的 React 教程站设为 7 篇LCP最大内容绘制从 3.2s 降至 1.8s新闻聚合站短摘要12–15 篇用户快速扫读需要更高信息密度摘要卡片高度固定布局更可控客户的行业资讯站14 篇跳出率下降 22%作品集展示大图为主9 篇平衡图片加载与页面长度9 是 3×3 网格的天然倍数CSS Grid 布局无冗余设计师个人站9 篇移动端滚动流畅度提升明显注意limit值一旦设定必须同步更新createPages和模板中的 GraphQL 查询。我见过太多人改了createPages的limit却忘了改模板里的limit导致第一页显示 10 篇第二页只显示 5 篇因为skip计算错位。3.2 安装与基础配置四步完成 gatsby-awesome-pagination 集成Step 1安装依赖npm install gatsby-awesome-pagination # 或 yarn add gatsby-awesome-pagination提示无需额外安装gatsby-plugin-page-creator或其他分页插件gatsby-awesome-pagination是纯工具库无运行时依赖。Step 2在 gatsby-node.js 中编写 createPages 逻辑核心// gatsby-node.js const { createPagination } require(gatsby-awesome-pagination); exports.createPages async ({ graphql, actions }) { const { createPage } actions; // 1. 查询所有 Markdown 文章总数关键必须用 totalCount const result await graphql( query { allMarkdownRemark( sort: { fields: [frontmatter___date], order: DESC } ) { totalCount } } ); if (result.errors) { throw result.errors; } const totalCount result.data.allMarkdownRemark.totalCount; const postsPerPage 8; // 与模板中保持一致 // 2. 使用 createPagination 生成分页配置 // 注意path 参数必须以 / 开头且结尾带 /Gatsby 路由规范 createPagination({ createPage, // Gatsby 提供的 API component: require.resolve(./src/templates/blog-list.js), // 模板路径必须存在 totalCount, // 总文章数必填 itemsPerPage: postsPerPage, // 每页条数必填 pathPrefix: /blog, // 分页路径前缀可选默认为 / // 以下为高级配置按需开启 // resolvePagePath: ({ pageNumber }) /blog/archive/${pageNumber}/, // 自定义路径生成函数 // context: { siteTitle: My Blog }, // 额外注入的全局上下文 }); // 3. 【重要】单独创建首页/blog/避免与分页页混淆 // 因为 createPagination 默认生成 /blog/page/1/而首页通常是 /blog/ createPage({ path: /blog/, component: require.resolve(./src/templates/blog-list.js), context: { currentPage: 1, limit: postsPerPage, skip: 0, totalPages: Math.ceil(totalCount / postsPerPage), // 注入首页特有字段如 banner 图片 isHomepage: true, }, }); };关键细节解析totalCount必须来自 GraphQL 查询的totalCount字段不能用edges.length计算因为edges默认只返回前 20 条totalCount才是真实总数pathPrefix: /blog意味着分页页路径为/blog/page/2/而非默认的/page/2/这直接影响 SEO 和用户感知单独创建/blog/首页是最佳实践。createPagination默认从第 1 页开始生成/blog/page/1/但用户习惯访问/blog/且/blog/和/blog/page/1/是两个不同 URL需分别处理context中的isHomepage: true是为首页定制样式留的钩子比如首页显示 Banner分页页不显示。Step 3创建分页模板blog-list.js// src/templates/blog-list.js import React from react; import { graphql } from gatsby; import Layout from ../components/layout; import BlogPostCard from ../components/blog-post-card; const BlogListTemplate ({ data, pageContext }) { const { currentPage, totalPages, isHomepage } pageContext; const posts data.allMarkdownRemark.edges; // 1. 安全解构 pageContext防止构建时崩溃 if (!pageContext || typeof pageContext.currentPage ! number) { console.error(Invalid pageContext in blog-list.js:, pageContext); return Layoutdiv分页上下文错误请检查 gatsby-node.js 配置/div/Layout; } // 2. 生成分页导航链接关键路径必须与 createPagination 一致 const generatePagePath (pageNum) { if (pageNum 1 !isHomepage) { return /blog/page/1/; } if (pageNum 1 isHomepage) { return /blog/; } return /blog/page/${pageNum}/; }; return ( Layout h1{isHomepage ? 最新文章 : 第 ${currentPage} 页}/h1 {/* 文章列表 */} div classNameblog-grid {posts.map(({ node }) ( BlogPostCard key{node.id} post{node} / ))} /div {/* 分页导航 */} nav classNamepagination aria-label文章分页导航 ul {/* 上一页 */} {currentPage 1 ( li a href{generatePagePath(currentPage - 1)} ← 上一页 /a /li )} {/* 页码列表简化版生产环境建议用 ellipsis */} {Array.from({ length: totalPages }, (_, i) i 1).map((num) ( li key{num} a href{generatePagePath(num)} aria-current{num currentPage ? page : undefined} {num} /a /li ))} {/* 下一页 */} {currentPage totalPages ( li a href{generatePagePath(currentPage 1)} 下一页 → /a /li )} /ul /nav /Layout ); }; export default BlogListTemplate; // 3. GraphQL 查询必须包含 skip 和 limit 变量 export const pageQuery graphql query BlogListQuery($skip: Int!, $limit: Int!) { allMarkdownRemark( sort: { fields: [frontmatter___date], order: DESC } limit: $limit skip: $skip ) { totalCount edges { node { id excerpt(pruneLength: 200) frontmatter { title date(formatString: YYYY-MM-DD) description } fields { slug } } } } } ;关键细节解析pageQuery中的$skip和$limit变量必须声明为Int!非空整数否则 GraphQL 编译失败generatePagePath函数严格遵循createPagination的路径规则首页用/blog/分页页用/blog/page/{num}/确保链接绝对准确aria-currentpage是无障碍访问a11y标准屏幕阅读器会告知用户“当前在第 3 页”Google 也视其为 SEO 信号模板开头的pageContext安全校验是线上必备避免因构建时pageContext缺失导致整个页面白屏。Step 4配置 gatsby-config.js可选但推荐// gatsby-config.js module.exports { plugins: [ // 其他插件... { resolve: gatsby-plugin-canonical-urls, options: { siteUrl: https://www.yoursite.com, }, }, ], };gatsby-plugin-canonical-urls会自动为每个分页页添加link relcanonical标签例如/blog/page/2/的 canonical 指向自身防止 Google 把/blog/page/1/和/blog/当作重复内容。这是 SEO 基础项务必开启。3.3 深度优化让分页不止于功能更兼顾性能与体验3.3.1 首屏性能优化延迟加载非首屏分页数据Gatsby 默认会为所有分页页包括/blog/page/100/在构建时生成完整 HTML。但如果博客只有 50 篇文章/blog/page/100/就是无效页。更糟的是allMarkdownRemark查询会拉取全部数据即使某页只显示 8 篇GraphQL 仍需遍历所有节点计算totalCount。优化方案方案 A用gatsby-plugin-limit-node限制查询范围推荐安装gatsby-plugin-limit-node在gatsby-config.js中配置{ resolve: gatsby-plugin-limit-node, options: { type: MarkdownRemark, limit: 200, // 只处理最近 200 篇超出的忽略 }, },方案 B在 createPages 中预过滤数据更精准修改gatsby-node.js的 GraphQL 查询只取需要分页的子集// 替换原来的 totalCount 查询 const result await graphql( query { allMarkdownRemark( sort: { fields: [frontmatter___date], order: DESC } # 只查询可能被分页用到的数据比如最近 200 篇 limit: 200 ) { totalCount edges { node { id } } } } ); const totalCount result.data.allMarkdownRemark.totalCount; // 后续 createPagination 逻辑不变实测效果某博客从 1200 篇文章优化到只处理最近 200 篇gatsby build时间从 4m23s 降至 1m18s构建内存占用减少 65%。3.3.2 用户体验增强平滑滚动与加载状态反馈纯静态分页点击后是硬跳转体验生硬。添加简单 JS 增强// src/components/pagination.js import { navigate } from gatsby; export const handlePageClick (e, path) { e.preventDefault(); // 添加 loading 状态如按钮变灰 const link e.currentTarget; const originalText link.textContent; link.textContent 加载中...; link.disabled true; // 导航后恢复 navigate(path).then(() { link.textContent originalText; link.disabled false; }); };在blog-list.js的分页链接中调用a href{generatePagePath(currentPage - 1)} onClick{(e) handlePageClick(e, generatePagePath(currentPage - 1))} ← 上一页 /a注意此增强仅作用于客户端导航Gatsby Link服务端直出 HTML 仍保持原样符合渐进增强原则。4. 常见问题排查与独家避坑指南那些文档里不会写的血泪教训4.1 问题速查表高频报错与一键修复方案报错现象根本原因修复方案我的实测耗时pageContext is not definedcreatePages中未传context对象或context为空对象{}检查createPagination调用处确认component路径正确且文件存在在createPage调用前加console.log(Creating page with context:, context)8 分钟首次Cannot read property currentPage of undefined模板中pageContext解构错误或pageContext未注入在模板开头添加if (!pageContext) { return divLoading.../div; }检查gatsby-node.js中createPage的context是否有currentPage字段12 分钟路径拼写错误点击分页链接跳转 404path配置与createPagination的pathPrefix不一致或.htaccess重写规则缺失运行gatsby build后检查public/blog/page/2/index.html是否存在若存在但 404检查服务器是否配置了FallbackResource /index.htmlApache或try_files $uri $uri/ /index.htmlNginx25 分钟客户服务器 Nginx 配置未更新所有分页页内容相同都是第一页GraphQL 查询中skip和limit未使用pageContext变量或变量名拼写错误如currentPage写成currentPageNum在pageQuery中打印console.log(Skip:, $skip, Limit:, $limit)检查模板中pageContext字段名是否与createPagination生成的一致3 分钟$skip写成$skpiTypeError: Cannot convert undefined or null to objectpageContext中某个字段如previousPagePath为null但在模板中直接解构使用在模板中用可选链pageContext?.previousPagePath或添加默认值const { previousPagePath } pageContext5 分钟未处理边界情况4.2 独家避坑技巧来自 3 个生产站点的实战经验坑 1中文路径与 gatsby-awesome-pagination 的兼容性问题当你设置pathPrefix: /博客时createPagination会生成/博客/page/2/但某些 CDN 或服务器对 UTF-8 路径支持不佳导致 404。解决方案强制使用拼音路径。在gatsby-node.js中const { createPagination } require(gatsby-awesome-pagination); const pinyin require(pinyin); // npm install pinyin // 将中文前缀转为拼音 const blogPrefix /bo-ke; // 手动映射或用 pinyin(博客).join(-) createPagination({ createPage, component: require.resolve(./src/templates/blog-list.js), totalCount, itemsPerPage: 8, pathPrefix: blogPrefix, // 使用拼音前缀 });坑 2createPagination的resolvePagePath函数陷阱文档示例中resolvePagePath: ({ pageNumber }) /blog/${pageNumber}/但pageNumber是数字而createPagination内部会调用String(pageNumber)转字符串。如果你写成resolvePagePath: ({ pageNumber }) /blog/${pageNumber.toString().padStart(2, 0)}/期望生成/blog/01/但createPagination会再次调用String()导致/blog/001/。正确写法在函数内直接返回完整路径字符串不依赖外部转换resolvePagePath: ({ pageNumber }) { const paddedNum String(pageNumber).padStart(2, 0); return /blog/${paddedNum}/; },坑 3Gatsby v4 升级 v5 后的createPagesEphemeral兼容问题Gatsby v5 引入createPagesEphemeral用于临时页面但gatsby-awesome-pagination仍基于createPages。解决方案在gatsby-node.js中保留createPages并显式禁用createPagesEphemeral的干扰exports.createPages async ({ graphql, actions }) { // 你的 createPagination 逻辑... }; // 显式导出空的 createPagesEphemeral防止 Gatsby v5 自动调用 exports.createPagesEphemeral async () {};4.3 性能监控如何验证分页优化是否生效不要只看gatsby build时间用真实指标验证Lighthouse 测试在/blog/和/blog/page/2/分别运行 Lighthouse对比First Contentful Paint (FCP)和Largest Contentful Paint (LCP)优化后目标LCP ≤ 2.5s移动端FCP ≤ 1.5s。构建日志分析运行gatsby build --verbose搜索Created page确认生成的分页页数量与Math.ceil(totalCount / limit)一致搜索allMarkdownRemark确认 GraphQL 查询耗时是否显著下降。网络面板验证打开 Chrome DevTools → Network刷新/blog/page/2/查看page-data.json文件大小。优化前可能达 800KB含全部文章数据优化后应 ≤ 120KB仅本页 8 篇数据。我给客户做的最后一次审计分页页page-data.json从 1.2MB 降至 98KBLCP 从 4.7s 降至 1.9sGoogle Search Console 中“移动设备可用性”警告清零。5. 进阶扩展超越基础分页的实用场景实现5.1 多分类分页为不同标签/分类生成独立分页流你的博客有React、Gatsby、Design三个标签希望/tag/react/下的文章也支持分页。gatsby-awesome-pagination本身不支持多维度分页但可以组合使用Step 1在gatsby-node.js中为每个标签创建分页// 获取所有标签 const tagResult await graphql( query { allMarkdownRemark { group(field: frontmatter___tags) { fieldValue totalCount } } } ); tagResult.data.allMarkdownRemark.group.forEach((tagGroup) { const tagName tagGroup.fieldValue; const tagCount tagGroup.totalCount; if (tagCount 0) { createPagination({ createPage, component: require.resolve(./src/templates/tag-list.js), totalCount: tagCount, itemsPerPage: 6, pathPrefix: /tag/${tagName.toLowerCase()}, // /tag/react/ context: { tagName, // 传递标签名给模板 }, }); } });Step 2在tag-list.js模板中用pageContext.tagName过滤数据export const pageQuery graphql query TagListQuery($skip: Int!, $limit: Int!, $tagName: String!) { allMarkdownRemark( filter: { frontmatter: { tags: { in: [$tagName] } } } sort: { fields: [frontmatter___date], order: DESC } limit: $limit skip: $skip ) { totalCount edges { node { # ... 字段 } } } } ;关键$tagName变量必须在createPagination的context中注入并在pageQuery中声明。这样每个标签都有独立的分页逻辑互不干扰。5.2 服务端渲染SSR兼容为动态数据源添加分页支持如果博客部分内容来自 CMS如 Contentful需在gatsby-node.js中处理createPages时的异步数据获取exports.createPages async ({ graphql, actions, reporter }) { const { createPage } actions; // 1. 从 Contentful 获取文章列表假设已配置 gatsby-source-contentful const contentfulResult await graphql( query { allContentfulBlogPost(sort: { fields: publishDate, order: DESC }) { totalCount edges { node { contentful_id title publishDate } } } } ); if (contentfulResult.errors) { reporter.panicOnBuild(Error loading Contentful data, contentfulResult.errors); } const totalCount contentfulResult.data.allContentfulBlogPost.totalCount; const postsPerPage 10; // 2. 创建分页逻辑同 Markdown createPagination({ createPage, component: require.resolve(./src/templates/contentful-blog-list.js), totalCount, itemsPerPage: postsPerPage, pathPrefix: /cms-blog, }); };此时contentful-blog-list.js的 GraphQL 查询需改为allContentfulBlogPostpageContext字段名保持一致即可。gatsby-awesome-pagination对数据源完全无感只关心totalCount和itemsPerPage。5.3 PWA 离线分页支持让分页页在无网时也能访问Gatsby 默认的gatsby-plugin-offline会缓存所有生成的 HTML 页面包括/blog/page/2/。但需确保gatsby-plugin-offline在gatsby-config.js中启用gatsby build后public/blog/page/2/index.html确实存在Service Worker 正常注册检查浏览器 Application → Service Workers。测试方法gatsby build→npx serve -s public→ 打开/blog/page/2/→ 点击 Chrome DevTools → Application → Service Workers → Click Update on reload → 断网 → 刷新页面。如果页面正常显示说明离线分页已生效。我在线上环境实测用户在地铁无网时访问/blog/page/3/Service Worker 返回缓存的 HTML文章列表完整显示仅评论区动态加载显示“离线中”。这是静态站点的天然优势无需额外开发。6. 最后的实操心得一个老手的三条硬核建议我在 Gatsby 生态里做了五年主题开发亲手交付过 17 个含复杂分页的商业站点最后分享三条不写在文档里、但每次都能救命的建议第一条永远先写createPages再写模板最后写查询。新手常犯的顺序是先写好blog-list.js再想怎么传pageContext结果发现createPages里漏了字段。正确顺序是