前端静态站点Web框架【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址https://gitcode.com/gh_mirrors/ga/gatsby点击查看免费下载本文基于仓库内 docs/docs/reference/release-notes/v4.10/index.md 展开。gatsby4.10.0是 Gatsby 于 2022 年 3 月发布的第二个小版本其核心亮点是正式引入Image CDN能力通过全新的RemoteFileGraphQL 接口与gatsbyImage解析器让远程图片「按需下载、按需处理」从而显著缩短构建时间并提升前端体验。读完本文你将掌握 Image CDN 的查询语法、gatsbyImage全部参数与默认值、源码级实现原理以及如何在自己的 source 插件中启用 Image CDN 支持。版本概览v4.10 带来了什么gatsby4.10.02022 年 3 月第二次发布的关键亮点只有一个但分量十足——Image CDN。除此之外本次发布还包含一批值得注意的 bugfix 与改进详见下文「Notable bugfixes improvements」一节。若想抢先体验新特性文档建议安装gatsbynext分支版本进行试用。上一版本的发布说明位于 v4.9 Release Notes。核心主题Image CDN为什么需要 Image CDN在 Image CDN 出现之前source 插件拿到远程图片后通常要经过「下载 → 落盘 → 交给 sharp 处理 → 产出多尺寸图片」的完整链路。gatsby-source-filesystem提供的createRemoteFileNode就是这种模式的代表详见 Preprocessing External Images 指南。这种做法会在构建阶段消耗大量时间与算力图片越多构建越慢。Image CDN 改变了这一局面source 插件在构建时不再需要把远程文件下载到本地只需把远程 URL 及相关元数据暴露为实现了RemoteFile接口的 GraphQL 节点新的GatsbyImage解析器即gatsbyImage字段按需下载图片并在构建期间处理从而减少构建时间、改善用户体验在 Gatsby Cloud 等支持 CDN 的平台上所有图片处理被推迟到边缘节点执行构建速度进一步提升——你甚至可以完全移除构建阶段内的图片处理步骤。需要注意的是仓库文档并未给出具体的性能数字例如「构建提速 X%」因此本文不引用任何未经证实的量化结论。从源码结构可以确认的是Image CDN 的核心思路是把「下载 处理」从构建主流程中剥离出来。RemoteFile GraphQL 接口Image CDN 的技术底座是RemoteFile接口。在 Gatsby 的 schema 层该接口由 packages/gatsby/src/schema/types/remote-file-interface.ts 中的getOrCreateRemoteFileInterface注册其字段实际由gatsby-plugin-utils的 polyfill 模块提供getRemoteFileFields。接口形状如下interface RemoteFile { id: ID! mimeType: String! filename: String! filesize: Int width: Int height: Int publicUrl: String! resize(/* args */): RemoteFileResize gatsbyImage(/* args */): GatsbyImageData }各字段含义与约束依据 creating-a-source-plugin 教程 Part 6必填publicUrl图片/文件的 URL、mimeType如image/jpg、application/pdf、filename图片节点额外必填width、height可为 nullfilesize、width、height、resize、gatsbyImage——因为RemoteFile同样服务于 PDF 等非图片资产resize与gatsbyImage由 Gatsby 自动提供是基于节点既有数据的 GraphQL 解析器。在源码层面接口字段定义于 packages/gatsby-plugin-utils/src/polyfill-remote-file/index.ts除id/mimeType/filename/filesize/width/height外还包括publicUrl、resize、gatsbyImage三个解析器字段同文件还导出了addRemoteFilePolyfillInterface用于把RemoteFile接口动态挂载到实现了它的类型上。gatsbyImage 解析器与查询示例启用 Image CDN 后你的 GraphQL 查询可以直接对实现了RemoteFile的节点调用gatsbyImage字段。v4.10 发布说明给出了一个典型示例query { speakerPage { socialImage { gatsbyImage(layout: FIXED, width: 440) } image { gatsbyImage(layout: CONSTRAINED, width: 280, height: 280) } } }解析器实现位于 packages/gatsby-plugin-utils/src/polyfill-remote-file/graphql/gatsby-image-resolver.ts。从源码看gatsbyImage的校验与默认行为包括layout参数必填否则抛出The layout argument is requiredwidth与height至少提供一个否则抛出错误默认formats为[auto, webp, avif]默认outputPixelDensities为[0.25, 0.5, 1, 2]常量DEFAULT_PIXEL_DENSITIES默认breakpoints为[750, 1080, 1366, 1920]常量DEFAULT_BREAKPOINTS默认fit为cover默认placeholder为dominantColor主色占位TRACED_SVG已废弃传入时会被警告并回退到主色占位默认quality为 75常量DEFAULT_QUALITY。gatsbyImage 参数全表下表依据generateGatsbyImageFieldConfig中的参数声明gatsby-image-resolver.ts整理可直接用于你的查询参数类型默认值说明layoutRemoteFileLayoutCONSTRAINEDFIXED固定尺寸FULL_WIDTH随容器宽度缩放CONSTRAINED随容器缩放但不超过最大宽度widthInt—FIXED下的显示宽度 /CONSTRAINED下最大图片的显示宽度实际最大分辨率会乘以outputPixelDensities中的最大值FULL_WIDTH下忽略heightInt—若省略则按源图宽高比由width推算placeholderRemoteFilePlaceholderDOMINANT_COLORBLURREDbase64 模糊图/DOMINANT_COLOR主色默认/TRACED_SVG已废弃回退主色/NONEaspectRatioFloat—指定宽或高后按此比例推导另一维必要时裁切formats[RemoteFileFormat][AUTO, WEBP, AVIF]AUTO/JPG/PNG/WEBP/AVIF不建议同时指定PNG与JPGoutputPixelDensities[Float][0.25, 0.5, 1, 2]像素密度列表不会生成超过源图尺寸的图片且始终包含 1xbreakpoints[Int][750, 1080, 1366, 1920]指定要生成的图片宽度主要用于FULL_WIDTH不会生成超过源图的图片sizesString—传给img的sizes属性仅影响浏览器选择图片不影响生成结果backgroundColorString—包裹层背景色或「信箱式」裁切到其他宽高比时的背景色fitRemoteFileFitCOVER图片适配方式cropFocus[RemoteFileCropFocus]—裁剪焦点qualityInt75输出质量枚举取值范围枚举定义见 packages/gatsby-plugin-utils/src/polyfill-remote-file/graphql/get-remote-file-enums.tsRemoteFileFitCOVER、FILL、OUTSIDE、CONTAINRemoteFileFormatAUTO、JPG、PNG、WEBP、AVIFRemoteFileLayoutFIXED、FULL_WIDTH、CONSTRAINEDRemoteFilePlaceholderDOMINANT_COLOR、BLURRED、TRACED_SVG、NONERemoteFileCropFocusCENTER、TOP、RIGHT、BOTTOM、LEFT、ENTROPY、EDGES、FACESgatsbyImage 与 gatsbyImageData 的差异此前使用gatsby-plugin-image时查询字段是gatsbyImageData启用 Image CDN 后这一字段被gatsbyImage取代。发布说明明确指出两者的参数并非 100% 对齐但最常见的操作行为一致从教程文档Part 6可确认一个关键差异gatsbyImage必须提供width或height参数否则解析器会直接报错。在前端组件层面二者的消费方式基本一致——gatsbyImage返回的数据同样可以交给gatsby-plugin-image的GatsbyImage /组件渲染配合getImage工具函数。图片 URL 格式启用 Image CDN 后图片会从形如下方的相对 URL 提供服务/_gatsby/image/base64-string/base64-string/original-file-name.file-extension从源码 packages/gatsby-plugin-utils/src/polyfill-remote-file/utils/url-generator.ts 可以还原出该 URL 的构成路由前缀默认是_gatsby可通过环境变量IMAGE_CDN_ROUTE_PREFIX覆盖路径中的两个base64-string段分别是对远程图片 URL与图片处理参数w/h/fm/q 等做内容摘要createContentDigest得到的哈希值URL 查询参数由ImageCDNUrlKeys定义u明文 URL、eu加密 URL、a处理参数、cd内容摘要当同时设置了IMAGE_CDN_ENCRYPTION_SECRET_KEY与IMAGE_CDN_ENCRYPTION_IV环境变量时远程 URL 会使用 AES-256-CTR 加密后放入eu参数可通过IMAGE_CDN_HOSTNAME指定自定义 CDN 前端域名。开发服务器与构建期的处理链路在没有 CDN 提供方的本地环境中Image CDN 也能工作它会在开发服务器/构建期间自动回退为本地处理。HTTP 路由实现在 packages/gatsby-plugin-utils/src/polyfill-remote-file/http-routes.tsGET /_gatsby/file/:url/:filename代理远程文件下载后以流式返回用于publicUrlGET /_gatsby/image/:url/:params/:filename解析查询参数中的w宽度、h高度、fm格式、q质量默认 75调用transformImage完成缩放/格式转换后流式返回polyfillImageServiceDevRoutes在hasFeature(image-cdn)为真时跳过注册——即若当前 Gatsby 核心已内置 Image CDN则由核心接管路由。特性开关image-cdn的检测逻辑见 packages/gatsby-plugin-utils/src/has-feature.ts它通过读取gatsby/apis.json中的features列表判断当前 Gatsby 版本是否支持该能力。此外isImageCdnEnabled函数会检查GATSBY_CLOUD_IMAGE_CDN环境变量是否为1或truepolyfill-remote-file/index.ts。在自己的 source 插件中启用 Image CDNv4.10 发布说明明确邀请 source 插件作者为自定义插件启用 Image CDN 支持。仓库中 creating-a-source-plugin 教程 Part 6 提供了完整手把手指南。核心只有两个必要条件一个实现了RemoteFile接口的 GraphQL根节点类型节点创建时提供与RemoteFile期望匹配的必需字段。步骤一Schema 定制import type { GatsbyNode } from gatsby export const createSchemaCustomization: GatsbyNode[createSchemaCustomization] ({ actions }) { const { createTypes } actions createTypes( type ImageAsset implements Node RemoteFile { alt: String! } ) }步骤二创建节点import type { GatsbyNode } from gatsby import type { IRemoteImageNodeInput } from gatsby-plugin-utils export const sourceNodes: GatsbyNode[sourceNodes] (gatsbyApi) { const { actions, createNodeId, createContentDigest } gatsbyApi const { createNode } actions const remoteUrl https://images.unsplash.com/photo-1644310972589-643a2099d946?fmjpg const imageData { url: remoteUrl, placeholderUrl: ${remoteUrl}w%width%h%height%, mimeType: image/jpg, filename: red-rosa-infinity, width: 3000, height: 4000, alt: Red and rosa infinity thingy floating in air, } const node: IRemoteImageNodeInput { ...imageData, id: createNodeId(ImageAsset-${remoteUrl}), parent: null, children: [], internal: { type: ImageAsset, contentDigest: createContentDigest(imageData), }, } createNode(node) }要点提示均出自教程原文url字段应指向分辨率最高的图片版本placeholderUrl用于生成加载占位图若 API 支持按参数缩放可在 URL 中放置%width%、%height%占位符如 Unsplash 的w参数否则直接提供一个最小尺寸图片的 URL 即可如果 API 不返回width、height、mimeType可以使用probe-image-size探测远程图片的元数据后再创建节点。一旦ImageAsset节点创建完成就可以在查询中调用gatsbyImage和resizequery { allImageAsset { nodes { gatsbyImage(width: 300) } } }需要特别说明本教程位于docs/目录之外发布其对应的仓库文档是 docs/docs/tutorial/creating-a-source-plugin/part-6/index.mdx其中还包含更完整的上下文Part 3 介绍了根节点实现Node接口Part 5/7 涉及gatsbyImage在页面组件中的消费。另外即使在没有 CDN 提供方的平台包括本地开发Image CDN 也会自动回退为构建期处理前端行为一致、构建不会失败。与 createRemoteFileNode 的对比新旧两条路径理解 Image CDN最好的参照物是它要替代的旧方案——createRemoteFileNode。旧方案的完整指南见 Preprocessing External Images在gatsby-node.js的onCreateNode中对 Markdown 节点里指向外部图片的 frontmatter 字段调用createRemoteFileNode将远程图片下载为本地File节点再由gatsby-transformer-sharp处理出childImageSharp最终在模板中通过gatsbyImageData消费const { createRemoteFileNode } require(gatsby-source-filesystem) exports.onCreateNode async ({ node, actions: { createNode, createNodeField }, createNodeId, getCache, }) { if ( node.internal.type MarkdownRemark node.frontmatter.featuredImgUrl ! null ) { const fileNode await createRemoteFileNode({ url: node.frontmatter.featuredImgUrl, parentNodeId: node.id, createNode, createNodeId, getCache, }) if (fileNode) { createNodeField({ node, name: localFile, value: fileNode.id }) } } }createRemoteFileNode的实现位于 packages/gatsby-source-filesystem/src/create-remote-file-node.js它会对输入做严格校验createNodeId、createNode必须是函数且必须提供 cache 或getCache并以 URL 为 key 维护processingCache去重随后通过fetchRemoteFile下载文件、createFileNode生成 File 节点。注意它在文档中的描述是「下载远程文件先查缓存确保不重复请求再推入队列」——这正是 Image CDN 试图从构建主流程中剥离的「下载 落盘」成本。下图是旧方案在博客场景中的运行效果featured image 从远程 URL 拉取并渲染两条路径的核心差异可概括为维度createRemoteFileNode旧Image CDN /RemoteFile新构建期行为下载远程文件并生成本地 File 节点不落盘按需下载、按需处理或交由 CDN 边缘处理查询字段gatsbyImageDatachildImageSharpgatsbyImageRemoteFile接口节点类型File节点实现了RemoteFile接口的自定义节点适用平台所有平台所有平台无 CDN 时自动回退构建期处理现有采用情况WordPress 与 Contentfulv4.10 发布说明指出WordPress 与 Contentful 的 source 插件已经使用RemoteFile接口并启用了新的GatsbyImage解析器用户可以立即试用。其他主流 CMS 与本地文件支持随后跟进。这一说法在仓库源码中得到印证packages/gatsby-source-contentful/src/gatsby-plugin-image.js 中已有fetchRemoteFile、base64 占位图缓存inFlightBase64Cache/resolvedBase64Cache等按需拉取逻辑packages/gatsby-source-wordpress/src/steps/source-nodes/create-nodes/create-remote-file-node/index.js 使用better-queue管理远程文件下载任务并支持GATSBY_STALL_RETRY_LIMIT默认 3、GATSBY_STALL_TIMEOUT默认 30000ms、GATSBY_CONNECTION_TIMEOUT默认 30000ms等环境变量调优WordPress 插件还在 steps/create-schema-customization/index.js 中接入 schema 定制并在 steps/image-routes.ts 中提供图片路由。若你是自研 source 插件作者可对照上述两个插件与 creating-a-source-plugin 教程 的 Part 6/7 章节实现同样的RemoteFile接入。Notable bugfixes improvements除 Image CDN 外v4.10 还修复了一批问题均为发布说明原文要点PR 编号保留原文编号便于在 CHANGELOG 中对照gatsby核心修复编码后查询参数encoded query params的处理问题PR #34816修复错误的 inconsistent node counters 报错PR #35025创建 TypeScript 新项目时改用gatsby-config.ts文件PR #35128当查询重跑但结果未变化时不再重写 page-data 文件PR #34925减少无意义的磁盘写入。gatsby-plugin-sharp修复MaxListenersExceededWarning警告PR #35009升级probe-image-size以修复内存泄漏告警修复不同duotone设置下生成多张相似图片的问题PR #35075。此外社区贡献还涵盖了wrapPageElement()/wrapRootElement()文档范围修订、GatsbyFunctionRequest泛型、gatsby-transformer-excel使用readFileBuffer、缓存键拼写修复等细节。相关源码改动可分别在 packages/gatsby/src、packages/gatsby-plugin-sharp、packages/gatsby-transformer-excel 中查阅。版本脉络与后续演进前序版本v4.2 为远程文件基础设施打底gatsby-core-utils的fetchRemoteFile增加了基于 HTTP 状态码的重试能力PR #33461见 v4.2 Release Notes这是 Image CDN 按需下载可靠性的基础之一本次版本v4.10正式落地RemoteFile接口与gatsbyImage解析器后续版本仓库内 v5.x 系列 Release Notes 显示 Image CDN 在后续版本中持续演进如图片 CDN 的进一步平台化支持、GatsbyImageData类型等。结语Gatsby v4.10 的 Image CDN 是一次架构层面的转变把「远程图片的下载与处理」从构建主流程中剥离抽象为RemoteFile接口 gatsbyImage/resize解析器让 source 插件作者只需暴露元数据即可获得与本地图片一致的gatsby-plugin-image体验。对于使用者而言记住三件事即可快速上手查询字段从gatsbyImageData换成gatsbyImage且必须传width或height图片 URL 形如/_gatsby/image/digest/digest/filename.ext可通过IMAGE_CDN_HOSTNAME、IMAGE_CDN_ROUTE_PREFIX、IMAGE_CDN_ENCRYPTION_SECRET_KEY等环境变量定制自研 source 插件只需两步——Schema 中implements Node RemoteFile、节点创建时带上url/mimeType/filename/width/height等必需字段即可接入 Image CDN。想深入了解实现细节可继续阅读 RemoteFile 接口源码、gatsbyImage 解析器源码、Image CDN 路由源码或直接上手 creating-a-source-plugin 教程 Part 6 亲手实现一个支持 Image CDN 的插件。赞分享前端静态站点Web框架【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址https://gitcode.com/gh_mirrors/ga/gatsby点击查看免费下载相关推荐Gatsby v2.26 版本发布解析File System Route API、gatsby-plugin-image 与 Contentful v4 实战指南Gatsby v2.26 版本发布解析File System Route API、gatsby plugin image 与 Contentful v4 实战前端静态站点Web框架Gatsby 4.13.0 版本深度解析Image CDN 的 Traced SVG 占位图、开放 RFC 与一批关键修复Gatsby 4.13.0 版本深度解析Image CDN 的 Traced SVG 占位图、开放 RFC 与一批关键修复 Gatsby 4.13.0202前端静态站点Web框架Gatsby CLI 深度指南命令实战、版本演进与源码级实现解析Gatsby CLI 深度指南命令实战、版本演进与源码级实现解析 gatsby cli 是 Gatsby 生态中用于初始化、开发、构建与部署站点的官方命令行工前端静态站点Web框架创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考