Gatsby v4.20.0 发布说明深度解析GraphQL sort/聚合 API 变更 RFC 与 gatsby-plugin-mdx v4 RC【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby本篇技术指南围绕 Gatsbyv4.20.02022 年 8 月首个版本的官方发布说明展开逐一解读该版本的两个核心亮点——面向下一个大版本提出的 GraphQLsort/聚合字段 API 变更 RFC以及支持 MDX v2 的gatsby-plugin-mdxv4 候选版本RC——并深入剖析本版本涉及gatsby、gatsby-plugin-sass、gatsby-plugin-sharp、gatsby-plugin-utils、gatsby-source-wordpress、gatsby-source-drupal等包的重要修复与改进。读完本文你将理解新排序语法与旧语法sort: { fields, order }的区别及其在 Gatsby 5 中的最终落地方式掌握additionalData、catchLinks等新选项的配置方法并能定位到对应的源码实现进行验证。版本概览v4.20.0 带来什么gatsby4.20.0于 2022 年 8 月发布是 4.x 系列稳定迭代中的一个常规版本。其 Key Highlights 集中于两点RFC for changes insortand aggregation fields in Gatsby GraphQL Schema为下一个 Gatsby 大版本提出 GraphQL API 的破坏性变更方案目标是提升构建性能、降低资源占用。Release Candidate forgatsby-plugin-mdxv4支持 MDX v2并改进构建与前端性能、简化插件 API。此外该版本还包含一批值得关注的 bugfix 与改进。官方建议希望第一时间体验新特性的用户安装gatsbynext即 Bleeding Edge 版本上一版本内容可参考 v4.19 发布说明。RFCsort与聚合字段 API 的破坏性变更提案变更动机提升构建性能、降低资源占用官方在 v4.20 发布说明中明确提出Gatsby 正针对 GraphQL API 提出下一大版本的破坏性变更核心目标是通过重构sort与聚合字段group、min、max、sum、distinct的参数形态来提高构建性能并降低资源使用量。从源码结构看当前 4.x 中sort输入类型维护在 packages/gatsby/src/schema/types/sort.ts其输入字段使用字段枚举如第 178 行的fields: [fieldsEnumTC]节点模型在 packages/gatsby/src/schema/node-model.js 中通过const sortFields (sort sort.fields) || []解析排序字段——即以「字段枚举数组 排序方向」的扁平结构表达排序。而聚合字段则定义在 packages/gatsby/src/schema/types/pagination.ts每个allXxx分页类型上会挂载distinct、max、min、sum、group五个聚合字段其field参数同样是一个字段选择器枚举fieldTC。这种「枚举 扁平数组」的设计在字段较多、类型嵌套较深时会在 schema 生成阶段产生大量的枚举类型与连接字段这正是资源占用较高的根源。RFC 提案将参数改为**嵌套输入对象nested input object**形态从 schema 层面压缩类型图从而降低资源占用。语法对比从枚举数组到嵌套对象当前v4.x的sort语法{ allMarkdownRemark(sort: { fields: [frontmatter___date], order: DESC }) { nodes { ...fields } } }提案中的新语法{ allMarkdownRemark(sort: { frontmatter: { date: DESC } }) { nodes { ...fields } } }可以看到新语法不再需要fields数组与___双下划线分隔符而是直接把排序字段写成对象嵌套路径方向DESC/ASC作为叶子值结构上与数据本身的层级一致更加直观。RFC 的最终落地Gatsby 5 中的正式变更该 RFC 并非停留在提案阶段而是后续在 Gatsby 5 中正式落地。在 从 v4 迁移到 v5 的指南 中明确说明按照 RFCsort参数与聚合的field参数从枚举改为嵌套输入对象这一变更降低了资源使用并加快了 building schema 步骤。迁移指南同时给出了聚合字段的语法对照Before旧语法{ allMarkdownRemark { distinct(field: frontmatter___category) } }After新语法{ allMarkdownRemark { distinct(field: { frontmatter: { category: SELECT } }) } }注意聚合字段的新语法中叶子值使用的是SELECT选择该字段而非排序方向。使用 codemod 自动迁移迁移指南提供了官方 codemod通过gatsby-codemods包提供在项目根目录执行npx gatsby-codemodslatest sort-and-aggr-graphql .该命令会递归处理目录下所有相关文件如果只想迁移特定文件/目录可改为npx gatsby-codemodslatest sort-and-aggr-graphql filepath兼容性说明旧语法在 Gatsby 5 中仍可工作Gatsby 会自动套用同样的 codemod 在内部转换你的查询但官方强烈建议迁移到新语法——否则终端会出现弃用提示且旧语法查询在 GraphiQL 中无法正常工作。Release Candidategatsby-plugin-mdxv4 与 MDX v2 支持发布说明的另一大亮点是gatsby-plugin-mdx新大版本v4的候选版本RC发布。该版本的核心目标支持 MDX v2这是社区长期期待的能力改进构建与前端性能简化插件 API。从当前仓库 packages/gatsby-plugin-mdx/package.json 的依赖声明可以印证这一技术方向其依赖mdx-js/mdx: ^2.3.0与mdx-js/react: ^2.0.0、mdast-util-mdx: ^2.0.1即整套 MDX v2 生态。官方在发布说明中建议读者通过 MDX v2 RFC 了解详细设计值得注意的是本仓库中该包版本为5.17.0-next.0说明后续版本仍在持续演进。如果你希望试用这类预发布能力可按官方「Bleeding Edge」指引安装gatsbynext并反馈问题。Notable bugfixes improvements 逐项解析gatsby核心包保留head中 meta 标签的相对顺序修复了 Gatsby Head / 传统 head 管理中 meta 标签顺序可能被重排的问题保证文档头信息输出顺序稳定。修复gatsby develop的--host与--https选项此前这两个命令行选项在部分场景下不生效本版本通过两处 PR 修复了其解析与透传逻辑。改进 ContentSync 映射内容同步Content Sync的映射逻辑现在也会检查 Static Queries 与类型连接type connections使增量内容更新场景下的映射更完整。允许export { default }语法导出页面模板此前页面模板文件只支持默认导出的常规写法本版本放开了命名导出形式的export { default }方便以命名方式组织模板文件。修复gatsby serve中 DSG/SSR 的pathPrefix处理在使用pathPrefix且开启 DSGDeferred Static Generation或 SSRServer-Side Rendering时路径前缀此前可能未被正确应用本版本修复了该问题。提升自定义 resolver 字段上的排序/过滤/聚合性能对带有自定义 resolver 的字段执行 sort、filter、aggregation 时性能得到改进。gatsby-plugin-sass新增additionalData选项gatsby-plugin-sass在本版本新增了additionalData选项用于在实际入口文件之前前置注入 Sass 代码。该选项源自 sass-loader 的additionalData机制与覆盖 data 选项不同它只是将注入内容前置到入口内容之前。典型使用场景把环境变量以 Sass 变量的形式注入或前置一个全局 Sass 导入functions、mixins、variables 等供其他 Sass 文件复用。配置示例来自 gatsby-plugin-sass 的 READMEplugins: [ { resolve: gatsby-plugin-sass, options: { additionalData: $env: process.env.NODE_ENV ;, }, }, ]源码级验证在 packages/gatsby-plugin-sass/src/gatsby-node.js 中插件从 options 中解构出additionalData默认为undefined并原样传给sass-loader的 options第 26 行其插件选项 schema 校验同文件第 99-103 行通过 Joi 定义additionalData: Joi.alternatives() .try(Joi.string(), Joi.function()) .description( Prepends Sass/SCSS code before the actual entry file. ... )也就是说additionalData既可以是一个字符串也可以是返回字符串的函数用于动态计算注入内容。对应测试见 packages/gatsby-plugin-sass/src/tests/gatsby-node.js其中验证了非法值如数字123会触发 schema 校验错误additionalData must be one of [string, object]而字符串$test: #000;会被正确接受并传入 loader。gatsby-plugin-sharpBLURRED占位图确保最小 1px 高度修复了BLURRED占位图可能因宽高比计算出现 0 高度、进而导致生成失败或占位图异常的问题。从源码可以找到对应修复逻辑packages/gatsby-plugin-sharp/src/image-data.ts 中计算模糊占位图高度时使用height: Math.max( 1, Math.round(placeholderWidth / imageSizes.aspectRatio) ),即强制高度至少为 1 像素Math.max(1, ...)避免极宽图片等边缘场景下占位图高度为 0。同一文件中还定义了默认模糊图宽度DEFAULT_BLURRED_IMAGE_WIDTH 20第 16 行并支持通过blurredOptions.width覆盖。gatsby-plugin-utils修复 URL 编码问题修复了IMAGE_CDN与FILE_CDN对需要编码的 URL如包含空格、非 ASCII 字符的地址的处理确保远程图片/文件在 CDN 场景下能正确解析与访问。gatsby-source-wordpress新增catchLinks选项由于 WordPress 内容中的 HTML 字段链接非常常见gatsby-source-wordpress会自动安装并启用gatsby-plugin-catch-links用于拦截 HTML 字段中的锚点标签使其走客户端路由client-side routing而不是整页刷新。绝大多数站点这都工作良好但部分站点需要自行配置 catch-links 行为。本版本新增catchLinks插件选项默认值为true将其设为false即可禁用自动引入的那份gatsby-plugin-catch-links随后可自行安装并按需配置。配置示例来自 gatsby-source-wordpress 的 plugin-options 文档{ resolve: gatsby-source-wordpress, options: { catchLinks: false, }, }源码级验证在 packages/gatsby-source-wordpress/gatsby-config.js 中可以看到条件化注入逻辑module.exports ({ catchLinks true }) { // ... if (catchLinks) { // 注入 gatsby-plugin-catch-links } }且插件选项 schema 在 packages/gatsby-source-wordpress/src/steps/declare-plugin-options-schema.js 中以Joi.boolean()声明默认值true。更多说明可参考 gatsby-source-wordpress 的 gatsby-link 功能文档。gatsby-source-drupalContent Sync 支持翻译内容gatsby-source-drupal改进了 Content Sync 对翻译内容translated content的支持——具体实现是把langcode纳入 manifest ID 的生成从而保证同一节点的不同语言版本在内容同步时被正确区分与更新避免多语言站点的增量构建出现内容串扰或漏更。Contributors社区贡献一览本版本的修复与改进同样离不开社区贡献者主要包括按 PR 归属bytrangle在 remark 教程中补充安装 v2 版unist-util-visit的说明laneparton为gatsby-plugin-sass新增additionalData选项edlucas澄清 local font 操作指南中的说明Shubhdeep12修复debugging-html-builds文档拼写错误RajputUsman更新基础软硬件要求文档chrispecoraro修复 4.19 发布说明中的拼写tordans为navigate(-1)添加文档小节yanneves允许页面模板使用export { default }命名导出openscript为 TypeScript 测试补充依赖ThomasVandenhede修复gatsby-plugin-sharp的BLURRED占位图最小高度Hunta88修正语法billybrown-iii修复过期链接dan-mba在 Gatsby Head 参考文档中补充react-helmet说明Auspicus为gatsby-source-drupal的 manifest ID 添加langcodemerceyz补充缺失依赖axe312ger将gatsby-source-contentful迁移到最新版 Contentful SDK小结与升级建议gatsby4.20.0是一个「承前启后」的版本一方面通过gatsby-plugin-sass的additionalData、gatsby-source-wordpress的catchLinks、gatsby-plugin-sharp的占位图修复等带来立即可用的改进另一方面通过sort/聚合字段 API 变更 RFC 与gatsby-plugin-mdxv4 RC为下一个大版本的技术路线定下基调。对于希望在 Gatsby 5 正式发布前平滑过渡的开发者建议提前了解并逐步将 GraphQL 查询改写为嵌套对象的新语法可用npx gatsby-codemodslatest sort-and-aggr-graphql .辅助迁移关注gatsby-plugin-mdxv4 的 MDX v2 支持规划内容管线的升级路径如需体验预发布能力可安装gatsbynext进行验证。各包详细的变更与迁移上下文可继续阅读仓库中的 v4.19 发布说明、从 v4 迁移到 v5 指南 以及相关包的 README 与源码路径已在正文各节给出。【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考