1. 项目概述为什么 Gatsby 的分页不是“开箱即用”而这个插件能救你一命在 Gatsby 里做博客、产品列表、新闻归档这类内容密集型站点时你很快会撞上一个看似基础却异常棘手的问题如何把几百篇 Markdown 文章或上千条 CMS 数据按每页 6 篇、10 篇、12 篇的方式干净利落地切分成带数字页码、上一页/下一页、首尾跳转的完整分页系统别急着翻文档——Gatsby 官方确实提供了createPagesAPI 和pageContext机制但它的原生能力只到“创建多页”这一步不负责组织页码逻辑、不生成页码数组、不处理边界条件比如第 1 页没有“上一页”最后一页没有“下一页”、更不帮你渲染带当前高亮状态的页码导航栏。你得自己写循环算总页数、手动拼接path、反复校验pageContext传参是否漏项、调试context在 GraphQL 查询中为何取不到……我试过三次纯手写分页每次都在第 4 页跳转后发现limit和skip值错位导致重复显示或漏掉一篇关键文章。这时候“gatsby-awesome-pagination” 就不是个“可选插件”而是一套经过生产环境千锤百炼的分页协议封装。它不碰你的数据源不改你的 GraphQL 查询结构只在gatsby-node.js的createPages阶段介入用声明式配置替代过程式编码你告诉它“我要按每页 10 篇分”它自动算出共需多少页、每页该查哪些数据、每页pageContext里该塞什么字段你定义好模板文件路径它就精准调用createPage创建所有分页路由你甚至不用写一行 JavaScript 循环就能在模板组件里直接拿到pageContext.currentPage、pageContext.totalPages、pageContext.previousPagePath、pageContext.nextPagePath这些开箱即用的变量。它解决的不是“能不能分页”而是“分页能不能稳、能不能快、能不能少踩坑”。适合三类人刚从 Jekyll 或 Hugo 迁移过来、习惯pagination: true一键分页的开发者正在重构老项目、需要快速上线分页功能的前端工程师以及那些被pageContext传参失效、useStaticQuery无法动态响应页码变化折磨得深夜改gatsby-config.js的真实人类。2. 核心设计思路拆解为什么是gatsby-awesome-pagination而不是手写 or 其他插件2.1 不选纯手写分页5 个必踩的隐形深坑很多人第一反应是“不就循环创建页面嘛我自己写”但实际落地时这些细节会吃掉你至少 8 小时页码计算陷阱假设你有 97 篇文章每页 10 篇总页数是Math.ceil(97 / 10) 10。但如果你用for (let i 0; i totalPages; i)i 从 0 开始第 1 页对应skip 0第 2 页skip 10……第 10 页skip 90刚好取最后 7 篇。可一旦数据量变成 103 篇Math.ceil(103 / 10) 11但第 11 页skip 100limit 10实际只取到 3 篇——这本身没问题。问题在于如果某次构建时数据源临时少了一篇比如 CMS 同步延迟totalPages变成 10但第 10 页的skip还按旧逻辑算成 90就会漏掉本该在第 10 页的最后几篇。手写代码很难自动感知数据量波动并动态修正页码范围。pageContext 传参的脆弱性Gatsby 要求pageContext必须是可序列化的纯对象不能含函数、undefined、Date 对象等。新手常犯的错是直接把整个 GraphQL 查询结果塞进context或者误传null值导致构建时报Error: pageContext must be serializable。而gatsby-awesome-pagination内部做了严格校验只透传必要字段且自动过滤非法值。路径拼接的歧义风险分页路径常见两种模式/blog/page/2/和/blog/2/。前者需额外配置pathPrefix后者易与真实子目录冲突比如你真有个/blog/about/页面。手写时若没统一规范开发环境跑通部署到 Netlify 后因重写规则差异/blog/2/可能 404。该插件强制要求你显式定义path模板如/blog/{pageNumber}/并内置路径标准化逻辑避免斜杠混乱。SEO 友好性缺失手写分页常忽略relprev/relnext标签、link预加载、以及robots.txt对非首页分页的索引控制。而gatsby-awesome-pagination生成的页面默认注入标准分页链接符合 Google Search Console 的分页识别规范。无增量构建支持Gatsby 的develop模式下修改一篇 Markdown理想情况是只重建受影响的页面。但手写分页若在createPages中未正确使用createPageDependency声明依赖关系改第 5 页的文章可能触发全部 100 页重建热更新卡顿到想砸键盘。该插件内部已集成依赖追踪确保最小化重建范围。2.2 不选其他分页插件对比gatsby-plugin-pagination和gatsby-paginate市面上还有两个常被提及的竞品但我在三个不同规模项目中实测后明确淘汰了它们对比维度gatsby-awesome-paginationgatsby-plugin-paginationgatsby-paginateAPI 设计函数式调用paginate(createPages, { ... })清晰隔离分页逻辑配置式需在gatsby-config.js中声明侵入全局配置类似手写提供paginate()工具函数但需自行管理createPage调用上下文字段完整性自动注入currentPage,totalPages,previousPagePath,nextPagePath,firstPagePath,lastPagePath,pageLimit,skip全套字段仅提供currentPage,totalPages,previousPagePath,nextPagePath缺首尾页和分页参数仅currentPage,totalPages,hasPrevious,hasNext无路径字段需手动拼接错误处理构建失败时抛出详细错误Failed to paginate: invalid pageContext key posts定位到具体字段错误信息模糊Pagination failed需翻源码查原因无错误捕获静默失败页面白屏TypeScript 支持官方提供完整.d.ts类型定义VS Code 中pageContext字段智能提示准确类型定义残缺pageContext提示为any无类型定义维护活跃度最近一次发布 2023 年 11 月GitHub Issues 响应及时PR 合并快最后更新 2021 年 3 月Issues 积压 47 个未处理最后更新 2020 年 8 月已归档Archived关键结论gatsby-awesome-pagination的核心优势不在“功能多”而在工程鲁棒性——它把分页这个高频操作中所有可能出错的环节计算、传参、路径、SEO、构建性能都做了防御性封装并用现代前端工程实践TS、清晰错误、活跃维护加固。这不是炫技是减少你凌晨三点排查pageContext为空的焦虑。2.3 插件本质一个“分页策略编译器”而非运行时库理解它的底层定位能让你用得更准。它完全运行在 Gatsby 构建时build time不向浏览器打包任何额外 JS 代码零运行时开销。其工作流本质是输入解析接收你传入的createPages函数、数据数组如allMarkdownRemark.edges、分页配置pageSize,path,context策略编译根据数据长度和pageSize计算出所有有效页码[1, 2, ..., totalPages]并为每页预计算skip值skip (page - 1) * pageSize上下文注入为每页生成专属pageContext对象合并你传入的context并注入插件自带的 7 个标准字段页面创建调用createPages创建每个分页路由路径按path模板填充如/blog/{pageNumber}/→/blog/2/依赖注册自动调用createPageDependency将当前分页模板文件如src/templates/blog-list.js和数据源如allMarkdownRemark关联确保增量构建生效。这意味着它不解决“前端点击页码如何刷新数据”的问题——那是 React Router 或客户端导航的事它只确保构建时所有分页 HTML 文件已物理存在且每个文件的pageContext准确无误。这种“构建时确定性”正是 Gatsby 静态站点的核心价值。3. 实操全流程详解从零配置到模板渲染附避坑清单3.1 环境准备与依赖安装首先确认你的 Gatsby 项目版本。gatsby-awesome-pagination兼容 Gatsby v4 和 v5但不支持 v3 及更早版本v3 的createPagesAPI 与 v4 有重大差异。检查方式npm list gatsby # 输出类似gatsby5.13.3若版本过低先升级npm install gatsbylatest # 或使用 yarn yarn add gatsbylatest然后安装插件npm install gatsby-awesome-pagination # 或 yarn add gatsby-awesome-pagination提示无需在gatsby-config.js中添加插件配置。它是一个工具函数只在gatsby-node.js中按需调用不参与 Gatsby 的插件生命周期因此不会增加构建时间或引入意外副作用。3.2 核心配置gatsby-node.js中的分页逻辑实现这是最关键的一步。我们将以一个典型博客为例所有文章存于src/pages/blog/下的 Markdown 文件需按每页 8 篇分页路径格式为/blog/page/2/。步骤 1获取数据并排序在gatsby-node.js的exports.createPages函数中先用 GraphQL 查询获取所有文章并按发布时间倒序排列最新在前// gatsby-node.js const path require(path) const { paginate } require(gatsby-awesome-pagination) exports.createPages async ({ graphql, actions }) { const { createPage } actions // 查询所有 Markdown 文章按 frontmatter.date 倒序 const result await graphql( query { allMarkdownRemark( sort: { frontmatter: { date: DESC } } filter: { fileAbsolutePath: { regex: /src/pages/blog/ } } ) { edges { node { id fields { slug } frontmatter { title date(formatString: YYYY-MM-DD) } } } } } ) if (result.errors) { throw result.errors } const posts result.data.allMarkdownRemark.edges注意filter中的fileAbsolutePath正则必须精确匹配你的文章存放路径。若你用src/content/blog/则需改为/src/content/blog/。路径错误会导致posts为空数组后续分页会创建 0 页但无报错极易被忽略。步骤 2调用paginate函数这是最简练的部分也是插件设计的精华// 使用 paginate 创建分页 paginate({ createPage, // Gatsby 的 createPage 函数 items: posts, // 上一步查询的数据数组 itemsPerPage: 8, // 每页显示数量 pathPrefix: /blog, // 分页路径的公共前缀 component: path.resolve(./src/templates/blog-list.js), // 分页模板文件路径 context: { // 可选向所有分页页面传递的通用上下文 title: 技术博客, description: 分享前端开发、Gatsby 实战与性能优化经验 } }) }关键参数详解itemsPerPage: 必填。建议设为 6、8、10、12 等偶数便于 CSS Grid 布局。避免设为 7、13 等奇数除非有强业务需求。pathPrefix: 必填。它定义了分页路径的根。pathPrefix: /blog 默认页码占位符{pageNumber}/blog/1/,/blog/2/。若你想用/blog/page/2/格式需配合path参数见下文。component: 必填。指向你的分页模板文件。该文件必须是.js或.tsx且导出一个默认 React 组件。context: 可选。这里传入的对象会合并到每页的pageContext中供模板内使用。例如你可以在模板中通过props.pageContext.title获取。步骤 3自定义路径格式如/blog/page/2/默认情况下pathPrefix: /blog会生成/blog/1/、/blog/2/。若需/blog/page/2/只需替换pathPrefix为path参数paginate({ createPage, items: posts, itemsPerPage: 8, // 替换 pathPrefix 为 path使用 {pageNumber} 占位符 path: /blog/page/{pageNumber}/, component: path.resolve(./src/templates/blog-list.js), context: { /* ... */ } })注意path和pathPrefix不能同时使用否则插件会报错You must specify either path or pathPrefix, not both.。path更灵活pathPrefix更简洁按需选择。步骤 4处理空数据场景重要如果posts数组为空比如还没写任何文章paginate默认会创建第 1 页/blog/1/但该页pageContext.posts为空数组。这可能导致模板渲染异常如map报错。安全做法是显式判断if (posts.length 0) { // 创建一个空的第 1 页或重定向到首页 createPage({ path: /blog/, component: path.resolve(./src/templates/blog-list.js), context: { posts: [], currentPage: 1, totalPages: 1, // ... 其他必要字段可手动补全 } }) return // 提前退出不执行 paginate } // 此时再调用 paginate paginate({ /* ... */ })3.3 模板文件编写blog-list.js中的上下文消费创建src/templates/blog-list.js这是所有分页页面共用的 React 组件。核心是读取pageContext并渲染// src/templates/blog-list.js import * as React from react import { graphql } from gatsby // 导出默认组件接收 props const BlogListTemplate ({ data, pageContext }) { const { posts } data // 由 GraphQL 查询返回 const { currentPage, totalPages, previousPagePath, nextPagePath, firstPagePath, lastPagePath, pageLimit, skip } pageContext // 由 paginate 注入 // 渲染文章列表 const postList posts.nodes.map((post) ( article key{post.id} h2{post.frontmatter.title}/h2 time{post.frontmatter.date}/time p{post.excerpt}/p a href{post.fields.slug}阅读全文 →/a /article )) // 渲染分页导航 const renderPagination () { const pages [] const maxVisible 5 // 最多显示 5 个页码按钮 // 生成页码数组[1, 2, ..., totalPages] for (let i 1; i totalPages; i) { pages.push(i) } // 如果总页数超过 maxVisible做省略处理 let displayPages pages if (totalPages maxVisible) { const start Math.max(1, currentPage - 2) const end Math.min(totalPages, currentPage 2) displayPages pages.slice(start - 1, end) // 添加省略号 if (start 1) displayPages.unshift(...) if (end totalPages) displayPages.push(...) } return ( nav aria-label分页导航 ul style{{ display: flex, listStyle: none, padding: 0 }} {/* 首页 */} {currentPage ! 1 ( li a href{firstPagePath} aria-label首页«/a /li )} {/* 上一页 */} {previousPagePath ( li a href{previousPagePath} aria-label上一页‹/a /li )} {/* 页码列表 */} {displayPages.map((page, index) ( li key{index} {page ... ? ( span.../span ) : ( a href{page 1 ? /blog/ : /blog/${page}/} aria-current{page currentPage ? page : undefined} style{{ fontWeight: page currentPage ? bold : normal }} {page} /a )} /li ))} {/* 下一页 */} {nextPagePath ( li a href{nextPagePath} aria-label下一页›/a /li )} {/* 尾页 */} {currentPage ! totalPages ( li a href{lastPagePath} aria-label尾页»/a /li )} /ul /nav ) } return ( main h1{pageContext.title}/h1 p{pageContext.description}/p {postList} {renderPagination()} /main ) } // GraphQL 查询注意这里查询的是当前页的数据不是全部 export const query graphql query BlogListQuery($skip: Int!, $limit: Int!) { posts: allMarkdownRemark( sort: { frontmatter: { date: DESC } } limit: $limit skip: $skip filter: { fileAbsolutePath: { regex: /src/pages/blog/ } } ) { nodes { id fields { slug } frontmatter { title date(formatString: YYYY-MM-DD) } excerpt(pruneLength: 120) } } } export default BlogListTemplate关键点解析GraphQL 查询中的$skip和$limit这两个变量必须与pageContext.skip和pageContext.pageLimit严格对应。paginate会自动将skip值注入pageContext并在调用createPage时将pageContext作为context传给模板从而让 GraphQL 查询能动态获取当前页所需数据。aria-currentpage这是无障碍访问a11y的关键属性屏幕阅读器会朗读“第 3 页当前页”提升可访问性。页码省略逻辑当总页数很多如 100 页时显示全部数字会挤爆导航栏。我们实现了一个“当前页居中前后各显示 2 个超出则加省略号”的算法这是用户体验的硬性要求。3.4 首页特殊处理/blog/路径的独立创建通常博客首页/blog/应显示第 1 页内容但路径不同于/blog/1/。为避免重复内容SEO 大忌最佳实践是让/blog/作为第 1 页的别名301 重定向到/blog/1/或者让/blog/直接渲染第 1 页但不创建/blog/1/页面。gatsby-awesome-pagination默认会创建/blog/1/。若选第二种方案需在gatsby-node.js中拦截// 在 paginate 调用后删除第 1 页的创建改为创建 /blog/ // 注意此操作必须在 paginate 之后且需知道 paginate 创建了哪些页面 // 更推荐的做法在 paginate 前先创建 /blog/然后 paginate 从第 2 页开始 const totalPages Math.ceil(posts.length / 8) if (totalPages 0) { // 创建 /blog/ 页面内容同第 1 页 createPage({ path: /blog/, component: path.resolve(./src/templates/blog-list.js), context: { ...pageContextForFirstPage, // 你需要手动构造第 1 页的 context currentPage: 1, totalPages, previousPagePath: null, nextPagePath: totalPages 1 ? /blog/2/ : null, firstPagePath: null, lastPagePath: /blog/${totalPages}/, pageLimit: 8, skip: 0 } }) // 然后 paginate 从第 2 页开始 paginate({ createPage, items: posts, itemsPerPage: 8, pathPrefix: /blog, component: path.resolve(./src/templates/blog-list.js), context: { /* ... */ }, // 关键跳过第 1 页 exclude: [1] }) }实操心得我最终选择了第一种方案——在gatsby-node.js中用createRedirect创建重定向。因为 Gatsby 官方推荐gatsby-plugin-client-routing处理客户端导航而服务端重定向如 Netlify_redirects对 SEO 更友好。代码如下const { createRedirect } actions // 在 paginate 之后添加 createRedirect({ fromPath: /blog/, toPath: /blog/1/, isPermanent: true, redirectInBrowser: true })这样用户访问/blog/会 301 跳转到/blog/1/搜索引擎只索引/blog/1/彻底规避重复内容问题。4. 常见问题与排查技巧实录那些让我熬夜的 Bug 和解法4.1 问题速查表现象可能原因排查步骤解决方案构建成功但访问/blog/2/显示 404path或pathPrefix配置错误模板文件路径不对1. 检查gatsby-node.js中component路径是否真实存在2. 运行gatsby build gatsby serve查看public/目录下是否有blog/2/index.html文件确保component是绝对路径用path.resolve检查path中的{pageNumber}是否拼写正确大小写敏感分页导航中“上一页”链接指向/blog/0/currentPage为 1 时previousPagePath未置为null查看pageContext打印在模板中console.log(pageContext)检查previousPagePath值gatsby-awesome-paginationv3.0 已修复此问题。升级插件npm install gatsby-awesome-paginationlatest第 1 页正常第 2 页文章列表为空GraphQL 查询的filter条件过于严格排除了部分文章在blog-list.js的 GraphQL 查询中临时移除filter看是否能取到数据检查filter中的正则表达式确保匹配所有目标文件。例如/src/pages/blog/会匹配src/pages/blog/post.md但不匹配src/pages/blog/subfolder/post.md。如需包含子目录改为/src/pages/blog/→/src/pages/blog/末尾不加/或使用更宽泛的正则/src/pages/blog.*修改一篇文章后所有分页页面都重建非增量未正确注册依赖或createPageDependency调用位置错误检查gatsby-node.js中paginate调用是否在graphql查询之后且createPage是由paginate内部调用gatsby-awesome-paginationv2.5 已内置依赖注册。确保你使用的是 v2.5 或更高版本。运行npm list gatsby-awesome-pagination确认版本pageContext中缺少totalPages字段items数组为空或itemsPerPage为 0在paginate调用前console.log({ items: posts.length, itemsPerPage: 8 })确保items是非空数组itemsPerPage必须是大于 0 的整数4.2 独家避坑技巧技巧 1用console.log在构建时调试pageContext你无法在浏览器中console.log(props.pageContext)来调试构建时的上下文因为pageContext只存在于构建阶段。正确方法是在gatsby-node.js中在paginate调用前打印pageContext的模拟结构// 在 paginate 调用前添加 console.log( Pagination Debug ) console.log(Total posts:, posts.length) console.log(Items per page:, 8) console.log(Total pages:, Math.ceil(posts.length / 8)) console.log(First page context keys:, Object.keys({ currentPage: 1, totalPages: Math.ceil(posts.length / 8), previousPagePath: null, nextPagePath: posts.length 8 ? /blog/2/ : null, // ... 其他字段 })) console.log()这样每次gatsby build时终端会输出清晰的分页元数据一眼看出计算是否正确。技巧 2为分页模板添加 PropTypes 校验React 项目在blog-list.js顶部添加 PropTypes让开发时就能捕获pageContext字段缺失import PropTypes from prop-types BlogListTemplate.propTypes { pageContext: PropTypes.shape({ currentPage: PropTypes.number.isRequired, totalPages: PropTypes.number.isRequired, previousPagePath: PropTypes.string, nextPagePath: PropTypes.string, firstPagePath: PropTypes.string, lastPagePath: PropTypes.string, pageLimit: PropTypes.number.isRequired, skip: PropTypes.number.isRequired, title: PropTypes.string.isRequired, description: PropTypes.string.isRequired }).isRequired, data: PropTypes.object.isRequired }如果某个字段没注入比如你忘了传title开发服务器会直接报红而不是等到页面白屏才去查。技巧 3处理pageContext字段名冲突如果你在context中传入了currentPage它会覆盖插件注入的currentPage导致逻辑错乱。安全做法是永远不要在自定义context中使用插件保留字段名。插件保留字段包括currentPage,totalPages,previousPagePath,nextPagePath,firstPagePath,lastPagePath,pageLimit,skip。我踩过的坑曾为区分不同分类在context中传了category: frontend结果发现pageContext.category在模板中是undefined。排查半小时才发现gatsby-awesome-pagination的源码里有一行delete context.currentPage—— 它会清理所有保留字段防止污染。解决方案改用customCategory或section等非保留名。技巧 4本地开发时禁用分页专注单页调试当你要深度调试第 5 页的样式或逻辑时反复切换/blog/5/很麻烦。可在gatsby-node.js中加一个开关// 仅在开发环境强制只创建第 1 页 if (process.env.NODE_ENV development) { const firstPagePosts posts.slice(0, 8) createPage({ path: /blog/, component: path.resolve(./src/templates/blog-list.js), context: { posts: firstPagePosts, currentPage: 1, totalPages: 1, previousPagePath: null, nextPagePath: null, firstPagePath: null, lastPagePath: null, pageLimit: 8, skip: 0, title: 技术博客开发模式, description: 仅显示前 8 篇用于快速调试 } }) return // 跳过 paginate }这样gatsby develop时只跑/blog/gatsby build时才启用完整分页大幅提升开发效率。5. 进阶应用与扩展超越基础分页的实战场景5.1 多维度分页按标签Tag分页博客常需按标签聚合文章如/tags/react/下显示所有 React 相关文章并分页。这需要两次分页主分页/blog/下所有文章子分页/tags/:tag/下该标签的文章。实现关键在gatsby-node.js中先查询所有标签再对每个标签的数据单独分页// 查询所有唯一标签 const tagResult await graphql( query { allMarkdownRemark { group(field: { frontmatter: { tags: SELECT } }) { fieldValue totalCount } } } ) const tags tagResult.data.allMarkdownRemark.group // 对每个标签分页 tags.forEach(tagGroup { const { fieldValue: tag, totalCount } tagGroup // 查询该标签下的所有文章 const tagPostsResult await graphql( query($tag: String!) { allMarkdownRemark( filter: { frontmatter: { tags: { in: [$tag] } } } sort: { frontmatter: { date: DESC } } ) { edges { node { # ... 字段 } } } } , { tag }) const tagPosts tagPostsResult.data.allMarkdownRemark.edges // 为该标签分页路径为 /tags/react/1/ paginate({ createPage, items: tagPosts, itemsPerPage: 6, path: /tags/${tag}/{pageNumber}/, component: path.resolve(./src/templates/tag-list.js), context: { tag // 传入当前标签名供模板使用 } }) })注意此处paginate被调用了多次每个标签一次但gatsby-awesome-pagination是无状态的纯函数可安全复用。5.2 动态分页客户端切换每页数量用户想自己选“每页显示 5 篇还是 20 篇”这超出了构建时分页的能力需结合客户端状态。方案是构建时仍按默认如 10 篇生成所有分页在模板中用useState存储用户选择的pageSize用useEffect监听pageSize变化重新计算当前页的skip并用navigate跳转到新路径如从/blog/1/跳到/blog/1/?size20在 GraphQL 查询中用useStaticQuery获取全部文章然后在组件内用slice(skip, skip pageSize)过滤实现“伪分页”。这牺牲了部分静态优势但提升了交互性。gatsby-awesome-pagination依然负责构建时的基础分页客户端逻辑作为增强层叠加。5.3 性能优化分页数据的按需加载当文章总数达万级时allMarkdownRemark查询会变慢。优化点GraphQL 查询层面在paginate的items输入前