Gatsby 增量构建（Incremental Builds）调试完全指南：从 `--log-pages` 到构建产物 diff

Gatsby 增量构建Incremental Builds调试完全指南从--log-pages到构建产物 diff【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby本文基于 Gatsby 官方调试文档系统讲解 Gatsby 增量构建Incremental Builds的工作原理、预期行为与完整调试方法。读者将掌握Gatsby 如何跟踪 HTML 生成的输入来决定哪些页面需要重新生成、如何用gatsby build --verbose --log-pages查看变更页面、如何通过两次构建的产物 diff 定位导致页面被重建的根因以及gatsby-ssr中直接使用fs、依赖当前时间等常见全量重建陷阱的规避方案。增量构建是什么如何启用自 Gatsby v3 发布起增量构建Incremental Builds正式面向所有用户开放。它的核心能力是只重新生成re-generate那些确实需要更新的 HTML 文件子集而不是每次构建都把所有页面全部重新渲染一遍从而显著缩短构建时间。要使用这一能力前提非常简单保留上一次构建产生的.cache与public目录。Gatsby 正是依靠.cache目录中持久化的状态即页面/查询/模板的脏标记记录与public目录中上一轮的 HTML 产物来判断这次哪些页面需要重做、哪些可以直接复用。这一点在源码中也得到了印证构建流程中的 HTML 产物清理与再生成逻辑位于 packages/gatsby/src/commands/build-html.ts 的buildHTMLPagesAndDeleteStaleArtifacts它先从 store 中计算出需要重新生成与需要删除的页面列表再据此增量构建或删除陈旧产物如果没有任何需要重建的页面构建会直接输出There are no new or changed html files to build.。工作原理Gatsby 如何跟踪 HTML 生成的输入要想理解为什么看到的生成页面比预期多首先需要明白 Gatsby 生成 HTML 文件时究竟跟踪了哪些输入。官方文档明确指出Gatsby 跟踪以下四类输入页面使用的页面模板page template页面查询page query的结果页面模板使用的静态查询static query的结果前端源码共享代码以及浏览器端gatsby-browser.js/ SSR 端gatsby-ssr.js文件本身。当这些输入自上一次构建以来发生变化时对应的 HTML 文件就会被标记为需要重新生成反之Gatsby 可以安全地复用上一次构建生成的 HTML 文件。在源码层面这一机制由 packages/gatsby/src/redux/reducers/html.ts 中的htmlReducer实现。它为每个页面维护一个trackedHtmlFiles记录并用一组位标志dirty flag来标记脏原因例如FLAG_DIRTY_NEW_ENTRY新创建的页面必然需要生成FLAG_DIRTY_DATA_CHANGED页面数据page-data哈希发生变化对应页面查询结果变化FLAG_DIRTY_BROWSER_COMPILATION_HASH浏览器端 webpack 编译哈希变化对应前端源码变化FLAG_DIRTY_SSR_COMPILATION_HASHSSR 渲染器编译哈希变化对应页面模板变化FLAG_DIRTY_STATIC_QUERY_RESULT_CHANGED静态查询结果哈希发生变化FLAG_DIRTY_CLEARED_CACHE缓存被清除后保险起见全部标记为脏。而真正决定哪些 HTML 要重建、哪些复用、哪些删除的是 packages/gatsby/src/commands/build-utils.ts 中的calcDirtyHtmlFiles它遍历所有被跟踪的 HTML 文件若对应页面已删除则标记删除若页面模式为 SSG 且文件处于 dirty 状态则标记重建否则标记复用。静态查询结果的变化还会通过markHtmlDirtyIfResultOfUsedStaticQueryChangedbuild-utils.ts反向查出使用了该静态查询的所有模板及其关联页面再统一置脏。这就是一个静态查询被共享布局组件使用时会波及全部页面的底层原因。预期行为哪些变更会触发超预期重建文档特别指出以下两类变更会让重建范围超出直觉但这属于预期行为无需当成 bug 排查修改 React 组件 / 页面这会导致 webpack 重新编译部分产物文件的文件名哈希hash发生变化Gatsby 必须重新生成页面以更新其中的link与script引用。修改被静态查询static query引用的内容会导致一个或多个.html文件被重建。如果该静态查询被所有页面模板共用例如共享布局组件中的静态查询则所有页面都会被重建。调试第一步用--log-pages查看变更页面最直接的调试手段是在构建命令上追加两个 flaggatsby build --verbose --log-pages构建结束时控制台会列出所有发生变化的页面info Built pages: Updated page: /foo/bar/这两个 flag 在 CLI 中的定义位于 packages/gatsby-cli/src/create-cli.ts--no-uglify用于构建时不压缩 JS 产物便于调试--log-pages用于记录自上次构建以来发生变化的页面--write-to-file用于把变更页面日志保存到文件供后续对比。其中--log-pages与--write-to-file目前属于隐藏选项hidden: true是为内部实验性功能保留的但依然可用于日常调试。对应的输出逻辑在 packages/gatsby/src/commands/build.ts当传入program.logPages时分别打印Updated page: ...需重建与Deleted page: ...需删除当传入program.writeToFile时还会把这两份列表分别写入.cache/newPages.txt与.cache/deletedPages.txt见 build.ts方便后续脚本化对比。调试第二步生成两次构建的 diff如果还想看清两次构建之间文件到底发生了什么变化可以对比两次构建的public产物。在项目目录中依次执行gatsby clean gatsby build --no-uglify cp -r public public-first-build如果你在排查某些改动导致比预期更多的.html被重建此时做出你的代码改动如果你在排查为什么每次构建都重建所有.html跳过改动保持原样继续。然后执行gatsby build --no-uglify --verbose --log-pages diff -u -r public-first-build public build-diff.diff打开位于站点根目录的build-diff.diff文件即可查看两次构建产物的全部差异。注意如果希望 diff 中排除所有.html文件即只关注资源与数据文件的变化可以改用diff -u -r --exclude*.html public-first-build public build-diff.diff--no-uglify的意义在于让产物中的 JS 尽可能保持可读从而便于人工对比构建完成后也可以清理临时目录public-first-build。理解 diff两大排查方向生成 diff 只是第一步正确解读它才是关键。你可以借助diffchecker.com之类的在线对比工具或使用代码编辑器的 diff 插件来更直观地阅读差异。文档给出了两个高价值的排查方向方向一检查 JS bundle 是否变化如果在 diff 中看到chunk-map.json、webpack.stats.json以及app-data.json的内容发生变化并出现类似Only in public: component---src-path-to-file-[hash].js的行说明组件本身在两次构建之间发生了改变。此时应对比两个.js文件找出具体改了什么。这与前面的预期行为一致组件源码变更 → webpack 产物哈希变化 → 页面中的script/link引用必须更新 → 相关页面被重建。方向二检查/page-data是否变化如果 diff 集中在/page-data目录说明静态查询和/或页面查询发生了变化因此对应页面被重建。区分方式page-data/sq/d/[hash].json发生变化 → 静态查询static query的结果变了它是罪魁祸首page-data/[page-title]/page-data.json发生变化 → 页面查询page query的结果变了。打开这些文件即可定位究竟是哪一个查询导致的连锁重建。这一行为同样能在源码中找到对应ADD_PAGE_DATA_STATSaction 会在pageDataHash变化时把页面标记为脏FLAG_DIRTY_DATA_CHANGED而静态查询结果哈希的变化则通过PAGE_QUERY_RUNaction 与FLAG_DIRTY_STATIC_QUERY_RESULT_CHANGED记录并传播见 packages/gatsby/src/redux/reducers/html.ts。实战 Tip 1避免在gatsby-ssr中直接调用文件系统Gatsby 虽然会跟踪上述输入但gatsby-ssr.js允许执行任意代码——例如直接使用 Node.js 的fs模块const fs require(fs) const someUntrackedInput fs.readFileSync(some-path.txt) // Rest of gatsby-ssr.js fileGatsby 理论上也可以跟踪被读取的文件但自定义代码中的文件读取可能包含 Gatsby 无法感知的特殊逻辑比如上面的例子中文件名可能是动态生成且在两次构建间变化或文件内容本身会变——这些都被 Gatsby 视为任意arbitrary文件读取。一旦 Gatsby 发现fs模块被使用就会直接禁用增量构建模式以保证安全构建时会给出提及 unsafe builtin method 的警告。从源码可以清楚看到这条降级路径SSR 渲染过程中一旦检测到不安全的内置模块调用会派发SSR_USED_UNSAFE_BUILTINaction 将unsafeBuiltinWasUsedInSSR置为true见 packages/gatsby/src/redux/reducers/html.ts随后 build-utils.ts 中的calcDirtyHtmlFiles会发出警告Previous build used unsafe builtin method. We need to rebuild all pages并在 build-utils.ts 处把所有页面强制标记为重建。如果你的站点或插件在gatsby-ssr中使用了fs读取请参考 从 v2 迁移到 v3 指南中的 Using fs in SSR 章节 进行迁移。该章节给出了标准迁移示例用import静态引入替代运行时fs.readFileSync例如import * as React from react -import * as fs from fs -import * as path from path import stylesToInline from !!raw-loader!/some-auto-generated.css export function onRenderBody({ setHeadComponents }) { - const stylesToInline fs.readFileSync(path.join(process.cwd(), some-auto-generated.css)) setHeadComponents( style dangerouslySetInnerHTML{{ __html: stylesToInline, }} / ) }实战 Tip 2避免依赖当前日期与时间在gatsby-node.js或gatsby-config.js中使用Date获取当前时间如new Date()、Date.now()获取并消费当前日期很可能就是每次构建都重建所有页面的元凶——因为日期在两次构建之间必然变化它被当作输入参与生成后所有相关产物都会失效。同样的道理也适用于查询buildTime{ site { buildTime } }如果在一个被所有页面共用的布局组件的静态查询中查询该字段就会导致所有页面每次构建都被重建。小结增量构建调试排查清单当重建的页面数量超出预期时可按以下顺序排查确认.cache与public目录未被清理/删除这是增量构建生效的前提用gatsby build --verbose --log-pages确认到底哪些页面被标记为重建、哪些被删除用gatsby clean gatsby build --no-uglify cp -r public public-first-build建立基线改动作废后再次构建并用diff -u -r对比两次产物重点检查chunk-map.json、webpack.stats.json、app-data.json对应 JS bundle 变化与page-data/目录对应静态/页面查询变化定位具体引发重建的输入检查gatsby-ssr.js及其使用的插件是否直接调用了fs留意 unsafe builtin method 警告以及gatsby-node.js/gatsby-config.js是否依赖当前时间或buildTime查询。增量构建只看输入、按需重建的机制决定了只要让输入保持稳定、可跟踪页面复用率就会最大化。借助本文的调试手段你可以精确回答这次构建为什么重建了这些页面从而有针对性地优化你的 Gatsby 站点构建性能。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考