Gatsby v3.2.0 发布解读StaticImage 错误改进、CSS Modules 的 ES Modules 开关与 Contentful 10 倍加速【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby本文基于仓库中的 v3.2 发布说明 展开系统梳理 Gatsby 3.2.0 的三个核心亮点——StaticImage构建期错误的可读性提升、四个 CSS 预处理插件对esModule/namedExport的可配置化以及gatsby-source-contentful5.2.0将抓取分页上限提升 10 倍带来的构建加速同时覆盖本版值得关注的 bugfix 与面向下一大版本的 remark 插件升级预告。读完本文你将能对照源码理解这些改动背后的实现原理并直接套用文中给出的配置示例完成升级与迁移。概述v3.2.0 的核心变化Gatsby v3.2.02021 年 3 月第三个版本主要聚焦三件事更好的StaticImage错误提示为gatsby-plugin-image中的StaticImage组件生成更易于定位问题的报错信息直接展示出错代码并附上文档链接CSS Modules 的可调 ES Modules 选项gatsby-plugin-sass、gatsby-plugin-less、gatsby-plugin-postcss、gatsby-plugin-stylus四个插件同步发布新 minor允许通过cssLoaderOptions覆盖css-loader的esModule与namedExport选项gatsby-source-contentful5.2.0Contentful 数据抓取的默认分页上限提升 10 倍显著缩短构建时间同时修复网络错误重试并完善相关文档。其余还包括一系列 bugfix以及一个面向后续版本的预告全部 remark 系插件将迎来一次 major bump底层解析器升级到 remark 13。更好的StaticImage错误提示StaticImage是gatsby-plugin-image提供的便捷组件用于渲染每次渲染内容相同的图片从而免去手写 GraphQL 查询的繁琐。但它有一个核心约束组件的src等属性必须在构建期可静态解析不能依赖运行时变量。v3.2.0 之前的报错信息过于笼统使用者往往不知道是哪一行代码触发了限制。本次改进让错误信息同时包含三部分内容一段对错误的文字描述一个 codeframe代码框精确定位到触发错误的源码行指向相关文档的链接。从源码实现看错误信息由 Babel 插件在编译期生成babel-plugin-parse-static-images.ts 会在解析StaticImage的 props 时检查是否存在无法在构建期解析的属性如src引用外部变量并把拼装好的错误通过__errorprop 注入组件见 static-image.tsx 中的IPrivateProps最终在浏览器/CLI 中渲染出来方便开发者一眼定位问题。Bonus 能力如果想把StaticImage用作背景图片本版新增了背景图片background images的用法文档配合backgroundColor等属性即可实现详见 gatsby-plugin-image 参考文档 中对backgroundColor、placeholder与dominantColor等选项的说明。说明发布说明中展示的 CLI 报错截图位于外部图床仓库内无对应本地图片此处以文字描述还原其内容。CSS Modules可调整的 ES Modules 选项背景v3 为何默认以 ES Modules 导入 CSS ModulesGatsby v3 起CSS Modules 默认以ES Modules方式导入而不是 CommonJS。这样做的好处是更好的 tree-shaking未使用的样式在打包时被剔除产物文件体积更小。但代价是如果项目依赖的第三方包仍按 CommonJS 方式消费 CSS Modules 的导出就会出现兼容性问题阻碍向 v3 迁移。四个插件同步支持esModule/namedExport覆盖v3.2 同步发布了gatsby-plugin-sass、gatsby-plugin-less、gatsby-plugin-postcss、gatsby-plugin-stylus的新 minor 版本允许在插件配置中通过cssLoaderOptions覆盖css-loader的两个关键选项选项作用源码中的默认值esModule控制 CSS Modules 是否以 ES Modules 语法导入true还是回退为 CommonJSfalse默认开启 ES ModulesGatsby v3 默认行为namedExport控制是否启用命名导出如styles.foofalse时回退为styles[foo]的访问方式默认true见各插件源码cssLoaderOptions.modules?.namedExport ?? true以 gatsby-plugin-sass 的 gatsby-node.js 为例onCreateWebpackConfig在构建.module.s(a|c)ss的 rule 时会把cssLoaderOptions透传给loaders.css()并把namedExport的默认值定为true用户可通过modules.namedExport覆盖。gatsby-plugin-less、gatsby-plugin-postcss、gatsby-plugin-stylus 的实现方式完全一致。配置示例回退到 CommonJS 行为若第三方包仍要求 CommonJS 风格可在gatsby-config.js中对相应插件做如下配置以 Sass 为例module.exports { plugins: [ { resolve: gatsby-plugin-sass, options: { cssLoaderOptions: { esModule: false, // 关闭 ES Modules 导入回退为 CommonJS modules: { namedExport: false, // 关闭命名导出 }, }, }, }, // less / postcss / stylus 同理 ], }gatsby-plugin-less与gatsby-plugin-stylus的完整迁移示例可参考 v2 到 v3 的迁移指南中CSS Modules 以 ES Modules 导入一节各插件的配置 schema 也已在源码中显式声明如 gatsby-plugin-sass 的 pluginOptionsSchema配置不合法时构建期即可收到报错。gatsby-source-contentful5.2.0同步提速与可靠性提升核心 Feature抓取分页上限提升 10 倍Contentful 插件通过 CDA sync API 拉取内容时按页抓取v3.2 将默认的每页条数上限提升了 10 倍DEFAULT_PAGE_LIMIT由 100 提升到1000见 plugin-options.js。请求页数大幅减少网络往返次数下降因此构建时间明显缩短。该值仍可通过插件配置的pageLimit选项自定义例如module.exports { plugins: [ { resolve: gatsby-source-contentful, options: { spaceId: process.env.CONTENTFUL_SPACE_ID, accessToken: process.env.CONTENTFUL_ACCESS_TOKEN, pageLimit: 500, // 默认 1000可按需调低 }, }, ], }配套机制pageLimit 自动退避backoff分页上限变大后单页响应体也可能变大存在触发 Contentful API Response size too big 上限的风险。因此 v3.2 在 fetch.js 中加入了pageLimit 自动退避逻辑当同步请求因响应体过大失败时插件会把当前 pageLimit 缩减为原来的 2/3Math.floor((currentPageLimit / 3) * 2)并以警告信息提示用户建议在 gatsby-config.js 中将 pageLimit 设置为 X 以避免同步失败然后重试直到成功。这一行为有对应的单元测试覆盖见 fetch-backoff.js如 1000 → 666 → 444 的退避序列断言。网络错误重试与容错修复网络错误会正确地再次重试修复了此前连接中断后不再重试的问题相关行为由 fetch-network-errors.js 验证支持通过contentfulClientConfig.retryOnError控制重试开关。为gatsby-plugin-image设置正确的默认值默认使用Constrained 布局 dominant color 占位图避免因缺失默认值导致的渲染异常。凭据错误提示更友好当连接凭据spaceId/accessToken错误时给出更明确的指引。downloadLocal文档补全downloadLocal配置项默认false的文档得到扩充便于需要本地化图片文件的用户理解其影响。示例项目与 e2e 测试仓库内的 using-contentful 示例 已升级到 Gatsby v3并演示如何配合gatsby-plugin-image使用 Contentful 图片新增 e2e-contentful 测试套件用于提升插件在真实数据环境下的可靠性。Notable bugfixes improvements本版还包含以下值得注意的修复与改进改动说明SSR 中使用fs的警告不再那么激进排除了http(s).Agent与node-gyp-build等合理场景减少误报PR #30216gatsby-plugin-image渲染修复修复占位图与组件本体的渲染问题PR #30221增量构建调试文档新增 Debugging Incremental Builds 文档PR #30329本地插件选项 schema 校验插件选项 schema 校验扩展到本地插件local plugins配置错误在构建期即可暴露PR #29787下一个版本预告remark 系插件 major bumpRemark 解析器近期发布了 major 升级remark 13底层解析机制发生变更。Gatsby 计划为所有 remark 相关插件发布新的 major 版本官方已放出alpha-remark13前缀的 canary 版本供提前验证。升级后产物可能仍存在细微差异与边界情况官方建议使用者在自己的package.json中安装以下 canary 版本并反馈问题gatsby-remark-autolink-headersalpha-remark13 gatsby-remark-code-replsalpha-remark13 gatsby-remark-copy-linked-filesalpha-remark13 gatsby-remark-custom-blocksalpha-remark13 gatsby-remark-embed-snippetalpha-remark13 gatsby-remark-graphvizalpha-remark13 gatsby-remark-images-contentfulalpha-remark13 gatsby-remark-imagesalpha-remark13 gatsby-remark-katexalpha-remark13 gatsby-remark-prismjsalpha-remark13 gatsby-remark-responsive-iframealpha-remark13 gatsby-remark-smartypantsalpha-remark13 gatsby-transformer-remarkalpha-remark13这些插件在当前仓库中均有对应实现例如 gatsby-remark-images、gatsby-remark-prismjs、gatsby-transformer-remark 等可作为升级前后的对照参考。小结Gatsby v3.2.0 通过更友好的StaticImage错误提示降低了图片组件的上手门槛通过esModule/namedExport可配置化解决了 CSS Modules 向 v3 迁移的兼容性痛点并通过gatsby-source-contentful5.2.0的 10 倍分页上限与自动退避机制显著提升了内容同步的构建性能与稳定性。对于仍在 Gatsby v2 的项目本版对应的迁移指南是升级 v3 的重要参考对于已经使用 v3 的项目则可直接按文中配置升级相关插件体验更快的构建与更稳定的 Contentful 同步。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考