企业官网建设流程全解析

• 前端
• 静态站点
• Web框架

gatsby-remark-images是 Gatsby 生态中处理 Markdown 图片的核心插件：它把 Markdown 中的相对路径图片转换为带弹性容器、srcset/sizes响应式属性、模糊占位与浏览器原生懒加载的 HTML，从而避免页面布局跳动并显著优化图片加载体验。本文以该插件仓库内 CHANGELOG.md 的版本演进为主线，结合 源码实现、插件选项 Schema 与 测试用例，完整梳理插件工作原理、全部配置项、格式支持边界与破坏性变更，帮助你准确理解其能力范围并在实际项目中正确配置。

插件定位与工作流程

它解决了什么问题

Markdown 里的普通alt最终只是一个固定尺寸的<img>标签，在移动端、高分屏和弱网环境下都存在明显短板。插件在构建期（Gatsby Node 侧）对图片做三件核心事（见 README.md）：

1. 加入弹性容器：生成一个按图片纵横比撑开高度的容器（源码中以padding-bottom: ${ratio}实现，见 src/index.js），图片加载过程中页面不会发生布局跳动（layout jump）。
2. 生成多宽度版本：基于容器maxWidth生成多种宽度的图片，并设置img元素的srcset与sizes，让不同设备宽度下载最合适的尺寸。
3. "blur up" 模糊占位：先展示一张约 20px 宽的极低分辨率占位图（base64），真实图片加载完成后淡入淡出替换，该技术由 Medium、Facebook 等站点率先普及。

构建期的处理链路

从 src/index.js 可以看到，插件是一个面向gatsby-transformer-remark的 remark 子插件，其主函数接收markdownAST、files、getNode、cache、getRemarkFileDependency等上下文。处理流程可归纳为：

1. 遍历 AST：用unist-util-visit-parents同时收集 Markdown 语法的图片节点（image、imageReference）和原生 HTML/JSX 中的<img>节点（src/index.js），并记录节点是否已处于<a>链接内（inLink）。
2. 解析图片信息：queryString.parseUrl剥离查询串后取扩展名，与supportedExtensions白名单比对（jpeg/jpg/png/webp/tif/tiff/avif，见 src/index.js）；只有相对路径（isRelativeUrl）且扩展名受支持才会被转换，外部 URL 与不支持格式原样保留。
3. 定位文件节点：由 Markdown 节点向上查找最近的File父节点，拼接出图片绝对路径；优先通过getRemarkFileDependency精确查询文件节点，否则回退到在files数组中线性查找（src/index.js）。
4. 调用 Sharp 生成响应式图片：调用gatsby-plugin-sharp的fluid生成多尺寸图片、srcset、base64占位与纵横比；若开启withWebp/withAvif，再分别以对应格式调用fluid并组装<picture><source>结构（src/index.js）。
5. 替换节点：将原图片节点替换为内联 HTML 节点（node.type = 'html'），最终产出span.gatsby-resp-image-background-image+img.gatsby-resp-image-image的组合，可选包上figure/figcaption与指向原图的链接。

浏览器端的淡入过渡

src/gatsby-browser.js 在onRouteUpdate中遍历所有.gatsby-resp-image-wrapper：初始把真实图片opacity设为 0，监听其load（或error）事件后给背景元素和图片元素设置 0.5s 的过渡动画，最后将背景占位淡出、图片淡入，并用box-shadow: inset 0px 0px 0px 400px ${backgroundColor}以配置的背景色覆盖占位区域，实现平滑的 "blur up" 效果。

安装与基础配置

插件对运行环境有明确要求：package.json中声明engines.node为>=18.0.0 <26，并以gatsby ^5.0.0-next与gatsby-plugin-sharp ^5.0.0-next作为 peerDependencies（package.json）。

npm install gatsby-remark-images gatsby-plugin-sharp

在gatsby-config.js中把它挂到gatsby-transformer-remark的plugins数组下：

// gatsby-config.js plugins: [ `gatsby-plugin-sharp`, { resolve: `gatsby-transformer-remark`, options: { plugins: [ { resolve: `gatsby-remark-images`, options: { // 内容容器宽度（像素），插件以它为基础生成不同宽度版本 maxWidth: 590, }, }, ], }, }, ]

仓库内的 benchmarks/markdown_id/gatsby-config.js 给出了同款组合的真实示例（maxWidth: 590，与gatsby-remark-responsive-iframe、gatsby-remark-prismjs、gatsby-remark-copy-linked-files、gatsby-remark-smartypants并列使用）。

Markdown 中引用图片时使用相对路径（相对于 Markdown 文件所在目录）：

Alt text here

默认情况下Alt text here会作为生成<img>标签的alt属性；若希望输出空的alt=""，可使用保留关键字GATSBY_EMPTY_ALT（该常量定义于 src/constants.js）：

[![GATSBY_EMPTY_ALT](https://raw.gitcode.com/gh_mirrors/ga/gatsby/raw/8999a2ed4dd8b40bab6571f7d23c7d196ebdb83e/e2e-tests/development-runtime/src/images/image.png?utm_source=gitcode_repo_files)](https://link.gitcode.com/i/1ccbb0269a7c0944eb02386a63e9a5d5)

配置项全解（默认值、取值与底层影响）

插件的完整选项默认值定义在 src/constants.js，并通过 src/gatsby-node.js 的pluginOptionsSchema（Joi）在构建期做校验。汇总如下：

关键选项的源码级说明

• showCaptions的取值逻辑：getImageCaption（src/index.js）把true归一化为['title', 'alt']，按数组中元素的顺序依次取title/alt；GATSBY_EMPTY_ALT会被视为空字符串跳过。caption 默认经_.escape转义防 XSS，markdownCaptions开启时改为经compiler.parseString/generateHTML渲染。测试 src/tests/index.js 覆盖了['title','alt']、['alt','title']、['title']、空数组等全部排列组合。
• wrapperStyle动态写法：README 给出的示例是用函数基于aspectRatio生成样式，例如：

{ resolve: `gatsby-remark-images`, options: { maxWidth: 800, // fluidResult.aspectRatio 参与计算 wrapperStyle: fluidResult => `flex:${_.round(fluidResult.aspectRatio, 2)};`, }, }

源码中wrapperStyle为函数时会以fluidResult作为参数调用并取返回值，否则直接作为样式字符串拼入包裹span（src/index.js）。

• srcSetBreakpoints的真实断点计算：默认情况下gatsby-plugin-sharp以maxWidth为基准生成 0.25x、0.5x、1x、1.5x、2x 与原始宽度的断点（packages/gatsby-plugin-sharp/src/index.js）；传入自定义数组后则改为「maxWidth+ 自定义断点」去重，且每个断点必须为正整数，否则构建直接抛错。注意srcSetBreakpoints上的默认DEFAULT_BREAKPOINTS = [750, 1080, 1366, 1920]属于gatsby-plugin-sharp的image-data.ts（非本插件默认断点），两者不要混淆。
• disableBgImageOnAlpha的判定：开启时会调用 Sharp 的stats检查图片isTransparent，为真则移除背景占位（src/index.js）；disableBgImage则无条件移除，且两者叠加时任一为真即移除。

选项校验（Joi Schema）

Schema 定义（src/gatsby-node.js）值得注意的约束包括：showCaptions只接受布尔值或['title'/'alt']数组；loading/decoding各自枚举了合法取值；withWebp/withAvif接受布尔值或{ quality: number }对象；wrapperStyle接受对象、单参数函数或字符串；srcSetBreakpoints为数字数组。这些约束与 CHANGELOG 中多次出现的 "Update pluginOptionsSchema tests"、"adding missing plugin options" 提交相呼应——插件选项从 v3 时代开始就逐步纳入 Gatsby 的插件选项校验体系。

支持的图片格式与边界

supportedExtensions白名单（src/index.js）支持的格式为：

• JPEG（.jpeg/.jpg）
• PNG（.png）
• WebP（.webp）
• TIFF（.tif/.tiff）
• AVIF（.avif）

由于图片处理基于 Sharp，GIF 与 SVG 不在转换之列：遇到这两种格式的 Markdown 图片引用时插件会直接放行（测试it leaves files with unsupported file extensions alone验证了.mp4等扩展名不被触碰，见 src/tests/index.js）。若仍想用 Markdown 图片语法渲染 GIF/SVG，README 建议搭配gatsby-remark-copy-linked-files，但这样只会原样加载文件，无法获得弹性容器与模糊占位等增强。

常见使用模式与测试验证

测试套件（src/tests/index.js，共 813 行）对插件行为做了非常细致的覆盖，可作为排查问题的"行为规范"：

• 引用式图片：[refImage1]: ./images/my-image.jpeg "Ref Image Title"配合![alt text][refImage1]会被转换，且引用节点中的 alt 会透传给定义节点；孤儿引用（无对应定义）原样保留。
• HTML 图片：原生<img src="./image.jpeg">也会被转换（经 cheerio 解析、替换），HTML 中可包含多个<img>；带查询串的路径（?query=string）同样支持——对应 CHANGELOG 中 "ensure query string is ignored when detecting images" 的修复。
• 已链接图片不重复加链：img与<a><img></a>均保持原链接结构，不会叠加linkImagesToOriginal生成的外链——这是 2018 年 "don't add links if image is already linked" 修复（issue #6982）确立的行为。
• 多图与混合场景：一条 Markdown 中混合引用式与内联式图片时逐一转换。
• 嵌套 Markdown 节点：当 Markdown 内容来自子节点（如JsonRemarkProperty等非File类型父节点）时，插件会沿 parent 链向上查找最近的File节点来定位图片目录——对应 2022 年 "support resolving markdown images from child nodes"（issue #28093）的修复。
• 非相对路径与不支持格式：外部 URL 图片、.mp4等格式一律不处理。

重要版本演进与破坏性变更（以 CHANGELOG 为主线）

gatsby-remark-images的版本号随 Gatsby 主版本走：当前分支下最新为7.16.0（2026-01-26），历史版本演进到 7.x 对应 Gatsby 5.x、6.x 对应 Gatsby 4.x、5.x/4.x/3.x 对应 Gatsby 3.x，更早的 2.x 属于 Gatsby 2 时代。以下按时间倒序梳理关键节点：

2026—2023：稳定期与格式扩展（7.x）

• 7.16.0（2026-01-26）：收紧 Node.js 版本范围声明，即engines.node为>=18.0.0 <26（issue #39398）。
• 7.14.0 / 7.13.2（2024）：两次将cheerio固定到精确版本（1.0.0-rc.12，见 package.json），规避依赖漂移对 HTML 图片解析的潜在影响。
• 7.4.0（2023-01-10）：修复 "Do not fallback title value to alt value"（issue #37395）——当图片没有title时不再把alt冒充为标题，避免figure结构下标题语义被破坏。
• 7.3.0（2022-12-13）：将avif加入supportedExtensions（issue #37112），与 2021 年先期加入的 AVIF 输出能力（见 3.10.0）形成闭环。
• 7.2.0（2022-11-25）：移除tracedSVG功能（issue #37093）。该选项虽仍在 Schema 中保留以兼容旧配置，但被.custom()校验器拦截：一旦传入非空值即打印 "no longer supported. Blurred placeholder will be used" 警告并强制回退到模糊占位（src/gatsby-node.js）。
• 7.0.0（2022-11-08）：随 Gatsby 5 大版本更新 peerDependencies 并应用 v5 补丁。

2021—2022：v4/v5 的能力扩充与精简（6.x）

• 6.14.0（2022-05-10）：支持从子节点（child nodes）解析 Markdown 图片（issue #28093），即上文"嵌套 Markdown 节点"能力。
• 6.6.0（2022-01-25）：修复"当被引用的图片发生变化时重新生成 Markdown"（issue #34433），保证增量构建中图片更新能正确反映到产物。
• 6.1.0（2021-11-02）：加入GATSBY_EMPTY_ALT的 figcaption 生成逻辑（issue #30468），并新增withAvif插件选项（issue #33658）。
• 6.0.0（2021-10-21）：移除sizeByPixelDensity选项（issue #33468），响应式尺寸策略统一收敛为srcSetBreakpoints体系。

2020—2021：选项体系成型（5.x / 4.x / 3.x）

• 5.10.0（2021-09-01）："Only convert supported image extensions"（issue #32868），确立扩展名白名单策略。
• 5.4.0（2021-06-09）：为生成的<img>增加decoding属性（issue #31558），默认async。
• 4.2.0 / 4.1.1（2021-03）：修复未决议的 Promise（issue #30418），避免构建挂起。
• 4.0.0（2021-03-02）：随 Gatsby 3 大版本更新 peerDependencies。
• 3.8.0 / 3.7.1（2020-12）：允许tracedSVG接受带配置的对象（issue #28242），并顺带升级 potrace 版本。
• 3.6.0 / 3.5.1（2020-11）：showCaptions支持传数组（['alt','title']等），并补齐插件选项定义（issue #27998 / #27944）。
• 3.5.0（2020-11-12）：允许wrapperStyle传字符串（issue #27912）。
• 3.4.0（2020-11-02）：接入 Gatsby 插件选项校验体系（"release plugin option validation"）。
• 3.3.26（2020-08-24）：修复 WebP 文件同样需要应用pathPrefix的问题（issue #26472）。
• 3.3.2（2020-05-08）：允许用wrapperStyle覆盖默认max-width（issue #23854）。
• 3.2.5（2020-04-22）：markdownCaptions支持在 MDX 中使用，并修复 remark 场景。

2018—2019：核心能力奠基（3.0 / 2.x）

• 3.1.11（2019-08-13）：新增markdownCaptions选项（issue #16574）。
• 3.1.10（2019-08-11）：支持浏览器原生懒加载，loading选项落地（issue #16448）。
• 3.0.14（2019-05-29）：缓存 tracedSVG 计算（cache 存在时），加速重复构建。
• 3.0.5（2019-02-22）：新增tracedSVG占位选项（issue #9490）。
• 3.0.0（2018-11-21）：引入 "blur up" 效果（issue #7800），并伴随重大破坏性变更：高清图img.gatsby-resp-image-image不再嵌套在低清占位span.gatsby-resp-image-wrapper内部，而是成为其兄弟节点。任何针对内联图片的自定义样式都可能因此失效——这也是之后多个 wrapper/背景样式修复（如 3.0.9 "override all default styling with wrapperStyle"、3.0.7 "wrapperStyle as a function"）的由来。
• 2.0.1-beta.8（2018-07-20）：支持 WebP 版本与回退（issue #6495）。
• 2.0.1-beta.7（2018-07-16）：将gatsby-plugin-sharp移入 peerDependencies。

版本选择与升级注意事项

• 跟随 Gatsby 主版本：插件各 major 与 Gatsby 主版本一一对应（7.x ↔ Gatsby 5、6.x ↔ Gatsby 4、5.x/4.x/3.x ↔ Gatsby 3、2.x ↔ Gatsby 2），升级 Gatsby 时需同步升级本插件及gatsby-plugin-sharp。
• 关注破坏性变更：v3.0.0 的 HTML 结构变化（影响自定义 CSS 选择器）、v6.0.0 移除sizeByPixelDensity、v7.2.0 移除tracedSVG是三个最需要迁移时检查的点；后两者若仍在配置中，前者会被构建期告警明确提示。
• Node 版本约束：当前版本要求 Node>=18.0.0 <26，低于 18 的运行时无法使用（该约束来自 7.16.0 的 "use more explicit node.js version range" 修复）。

如需查看更多仓库内佐证，可继续阅读 README.md、插件源码、选项 Schema、浏览器端过渡逻辑、完整测试套件 以及 benchmarks/markdown_id/gatsby-config.js 中的实战配置示例。

• 前端
• 静态站点
• Web框架