Gatsby Adapter 机制深入解析:gatsby-adapter-netlify 的版本演进、配置选项与源码实现

原创2026-09-20 19:26:421,680 阅读
文章标签:前端静态站点Web框架

Gatsby Adapter 机制深入解析:gatsby-adapter-netlify 的版本演进、配置选项与源码实现

gatsby-adapter-netlify 是 Gatsby 官方为 Netlify 提供的零配置部署适配器(adapter),它把 Gatsby 构建产物自动翻译为 Netlify 平台需要的 _redirects、_headers、Serverless Functions 与边缘函数配置。本文以该包 CHANGELOG.md 的版本演进为主线,结合其 README.md 与 src/ 下的核心源码,带你掌握适配器的安装、配置、能力边界以及底层实现原理,读懂后你能独立完成 Netlify 上的 Gatsby 站点部署、DSG/SSR 函数调优与 Image/File CDN 加速配置。

适配器是什么:Gatsby 的"平台翻译层"

Gatsby 5 引入了 adapter 概念:适配器是一个实现了 Gatsby 内部定义的 AdapterInit 接口的工厂函数,负责在构建结束时读取 Gatsby 生成的 routesManifest(路由清单)、functionsManifest(函数清单)与 headerRoutes(头部路由),并把它们转换为目标托管平台可识别的配置产物。

从 src/index.ts 可以看到,createNetlifyAdapter 返回的对象包含四个核心钩子:

  • cache.restore / cache.store:利用 @netlify/cache-utils 在 Netlify 构建缓存目录中恢复/保存 Gatsby 的 .cache 与 public 目录,实现部署间构建缓存,让后续构建"直接起飞"(源码注释中的原话:Found a Gatsby cache. We're about to go FAST. ⚡);
  • adapt():消费路由与函数清单,生成 Netlify 所需的一切运行时产物;
  • config():向 Gatsby 核心回报 deployURL、平台能力声明(supports)、需要禁用的旧插件列表、CDN URL 生成器模块路径等。

适配器属于 Gatsby 零配置部署能力的一部分:在 Netlify 上构建时会被自动安装。若需要更稳定的安装与自定义选项,可以手动安装。

安装与基本使用

在项目根目录执行:

npm install gatsby-adapter-netlify

然后在 gatsby-config.js 中通过 adapter 选项挂载:

const adapter = require("gatsby-adapter-netlify").default

module.exports = {
  adapter: adapter({
    excludeDatastoreFromEngineFunction: false,
    imageCDN: false,
  }),
}

需要满足的版本前提(来自 package.json):peerDependencies 要求 gatsby ^5.10.0-alpha,engines 要求 node >=18.0.0 <26。

两个核心配置选项

excludeDatastoreFromEngineFunction

(可选,默认 false)

  • 为 true 时,Gatsby 不会把 LMDB 数据存储(datastore)打进 SSR/DSG 所用的 Serverless Functions 包,而是把 datastore 上传到 Netlify CDN,函数在首次加载时再下载。这对减小函数包体积、规避部署平台的包大小限制很有价值。
  • 也可以通过环境变量 GATSBY_EXCLUDE_DATASTORE_FROM_BUNDLE=true 开启,这在零配置部署场景下尤其方便。
  • 从 src/index.ts 的源码看,该选项存在一个安全回退:当它被开启但没有可用的 DEPLOY_URL(本地 NETLIFY_LOCAL 时为 http://localhost:8888)时,适配器会打印 warning 并自动将其降级为 false,避免函数运行时找不到 datastore。

imageCDN

(可选,默认 false)

  • 为 true 时,Gatsby 不再在构建期下载并处理远程图片,而是把图片处理延迟到请求期,交给 Netlify Image CDN 完成。对使用 CMS 的站点(如 Contentful、Drupal、WordPress)可以显著缩短构建时间。
  • 也可以通过环境变量 NETLIFY_IMAGE_CDN=true 开启;源码中同时接受 true 与 1 两种字符串值(src/index.ts)。
  • 开启后需要在自己的 netlify.toml 中配置 [images] remote_images 白名单,允许外部图片域名,否则请求期无法拉取远程图片。

各 CMS 对应的 netlify.toml 示例

gatsby-source-contentful(spaceId 即插件配置中的空间 ID):

[images]
remote_images = [
  # <your-contentful-space-id> is specified in the `spaceId` option for the
  # gatsby-source-contentful plugin in your gatsby-config file.
  "https://images.ctfassets.net/<your-contentful-space-id>/.*"
]

gatsby-source-drupal(baseUrl 即插件配置中的站点地址):

[images]
remote_images = [
  # <your-drupal-base-url> is speciafied in the `baseUrl` option for the
  # gatsby-source-drupal plugin in your gatsby-config file.
  "<your-drupal-base-url>/.*"
]

gatsby-source-wordpress(url 即插件配置中的站点地址,无需包含 /graphql 路径):

[images]
remote_images = [
  # <your-wordpress-url> is specified in the `url` option for the
  # gatsby-source-wordpress plugin in your gatsby-config file.
  # There is no need to include `/graphql in the path here`
  "<your-wordpress-url>/.*"
]

如果你把 CMS 资源托管在其它域名或路径下,需要相应调整正则。另外,使用较新版本的 Contentful / Drupal / WordPress source 插件时,适配器会自动检测缺失的 Remote Path 模式并在构建日志中给出警告与建议配置——这是 allowed-remote-urls.ts 中 handleAllowedRemoteUrlsNetlifyConfig 的实现:它读取 netlify.toml(通过 @netlify/config),把其中的 images.remote_images 编译成正则,与 Gatsby 侧检测到的 remoteFileAllowedUrls 逐一比对,把缺失项以可直接粘贴的 TOML 片段输出到 reporter.warn。

适配器能力全景

按 README.md 与源码,该适配器在 Netlify 上开启的能力包括:

能力 说明 实现位置
Redirects 将 Gatsby createRedirect 产生的路由写进 public/_redirects route-handler.ts
HTTP Headers 将页面级 headers 写进 public/_headers 同上
默认缓存头 对静态资源应用 Gatsby 默认缓存策略 同上
DSG / SSR 为 Deferred Static Generation 与 Server-Side Rendering 生成 Netlify Functions lambda-handler.ts
Gatsby Functions 用户自建 API 函数同样转为 Netlify Functions 同上
构建缓存 跨部署复用 Gatsby cache src/index.ts
Image / File CDN 可选的请求期图片处理与文件代理 image-cdn-url-generator.ts、file-cdn-handler.ts

adapt() 的完整工作流

从 src/index.ts 的 adapt() 可以看到一次适配的四个步骤:

  1. 若启用了 imageCDN,先调用 handleAllowedRemoteUrlsNetlifyConfig 校验 netlify.toml 白名单;
  2. 调用 prepareFileCdnHandler 生成 File CDN 边缘函数(Edge Function)与清单;
  3. 调用 handleRoutesManifest(routesManifest, headerRoutes) 处理路由:生成 _redirects / _headers 并把静态文件移动到漂亮 URL(pretty URL)位置,同时返回"使用缓存(ODB)的 Lambda 名映射";
  4. 遍历 functionsManifest,为每个函数调用 prepareFunctionVariants 生成 Netlify Function 入口。

_redirects / _headers 的注入与兼容策略

route-handler.ts 是适配器最核心的翻译逻辑:

  • 重定向翻译:把 Gatsby 路由转成 Netlify _redirects 格式。查询参数形式的 fromPath 中 &/? 会被替换为空格,通配符 * 转为 Netlify 的 :splat;status 末尾追加 ! 表示强制重定向(force 语义);conditions 中仅 language、country 两个键被允许,且首字母大写后拼成 Language=xx,xx 形式(route-handler.ts 与 NETLIFY_REDIRECT_KEYWORDS_ALLOWLIST、NETLIFY_CONDITIONS_ALLOWLIST)。
  • 函数路由:route.type === "function" 时写 /.netlify/functions/<id>;若该路由声明了缓存(DSG),则写成 /.netlify/builders/<id>-odb,并把函数名登记进 lambdasThatUseCaching。
  • 动态路径:route.type === "static" 且路径含 /: 或 /* 时,把 :param 规范化为 <a href="https://link.gitcode.com/i/5b43dc26ea71902f84cae64d2e5c113b" target="_blank">param]、*param 规范化为 [...param]([pretty-urls.ts),并追加一条 200 重定向;同时把 HTML 文件移动到 public/<route>/index.html 或 public/<route>.html 这类漂亮 URL 位置(404.html、500.html 保持原地)。
  • 增量安全注入:injectEntries 用流式 Transform 把内容插入 public/_redirects / public/_headers,并识别三组标记区块——# gatsby-adapter-netlify start/end、旧 Netlify 构建插件 # @netlify/plugin-gatsby redirects start/end、以及旧插件 gatsby-plugin-netlify 的 ## Created with gatsby-plugin-netlify,自动剔除旧产物避免重复注入。这就是 CHANGELOG 中"handle cases with large cached _redirects and/or _headers files"修复的用武之地:文件再大也通过流式管道而非整体读入内存处理(route-handler.ts)。

Lambda Handler 的生成

lambda-handler.ts 为每个 Gatsby Function 写出 .netlify/functions-internal/<functionId>.js 与同名 .json 清单:

  • JSON 清单声明了 includedFiles(来自 fun.requiredFiles,路径中的 [/] 会转成 * 以满足 Netlify 语法)、includedFilesBasePath: process.cwd()、externalNodeModules: ["msgpackr-extract"](这是 LMDB 序列化所需的原生模块,必须外置)。
  • 生成的 JS 是一个"胶水 handler":把 Netlify 的 event/context 转换成 Node req/res 风格(复用 http.IncomingMessage.prototype 与一个自定义响应 Stream),再调用 Gatsby 提供的函数入口(通过 require 相对路径解析、支持 default 导出)。
  • 对于使用缓存(ODB/DSG)的函数,额外内联了一个 builder() 包装器:仅放行 GET/HEAD,剥离 query string,并给响应附加 metadata: { version: 1, builder_function: true, ttl: 0 },从而匹配 Netlify Builders 协议;其版本代码注释指出这是为了在 Node 24 上不再依赖回调式 @netlify/functions#builder。
  • prepareFunctionVariants 会同时生成普通版与 -odb 版两个函数变体,对应同一页面在"首次访问触发构建"与"缓存命中"两种状态下的处理。

Image / File CDN 的 URL 生成

开启 imageCDN 后,适配器通过 imageCDNUrlGeneratorModulePath / fileCDNUrlGeneratorModulePath 把 Gatsby 内部的图片/文件 URL 生成器替换为自己的实现:

  • image-cdn-url-generator.ts:把 width、height、cropFocus、format、quality 翻译为 Netlify Image CDN 的 w/h/fit=cover/position/fm/q 参数,并附带 url(远程源地址)与 cd(内容摘要)参数。
  • file-cdn-handler.ts:为"非图片文件"生成一个 .netlify/edge-functions/file-cdn/file-cdn.mts 边缘函数,它校验 url 是否匹配白名单正则后 fetch 远程资源;同时写入 manifest.json,把 {pathPrefix}/_gatsby/file/* 路径路由到该函数。非图片文件的 URL 中,远程地址会以 md5 哈希作为路径段(file-cdn-url-generator.ts)。

版本演进:从 1.0.0 到 1.4.0

结合 CHANGELOG.md 可以勾勒出该适配器的成熟轨迹:

1.0.x:基础能力与兼容性加固(2023-08 ~ 2023-11)

  • 1.0.0(2023-08-24):首个正式版本,随 Gatsby v5.12 发布,无功能性变更,仅为版本基线。
  • 1.0.1:修复大体积缓存 _redirects / _headers 文件的处理问题(issue #38559),即前面提到的流式注入。
  • 1.0.2:重定向尊重 force 与 conditions 属性(#38657)。
  • 1.0.3:适配器改用 headerRoutes(#38652),从"由 routesManifest 推导 headers"切换到"直接消费 Gatsby 核心给出的头部路由",使自定义 headers 的生成更准确。
  • 1.0.4:支持 pathPrefix 与 trailingSlash 选项(#38666)。

1.1.0:CDN 时代的开启(2023-12-18)

这是功能最密集的一次 minor 发布(Gatsby v5.13):

  • Image 与 File CDN URL 生成器适配器实现(#38685):正式落地 imageCDN 选项。
  • 支持 pathPrefix 与 trailingSlash(#38666 的继续)。
  • 适配器改用 headerRoutes(#38652)。
  • 尊重重定向的 force / conditions(#38657)。
  • 处理大缓存 _redirects / _headers(#38559)。
  • 为缓存处理补充了日志输出(#38654)。

后续 1.1.1(更新 remote url 文档)、1.1.3(补充 fs 方法重写以支持 DSG/SSR 引擎中的 fetchRemoteFile)、1.1.4(Windows 上 handler 生成修复)、1.1.5(DSG/SSR 渲染在不需要时可免于访问 datastore)、1.1.6(adapt() 性能优化)均是对 1.1.0 的能力打补丁。

1.2.0:工程化与性能(2024-11-06,Gatsby v5.14)

  • 功能:允许 DSG/SSR 渲染在不需要时不访问 datastore(#38974),与 excludeDatastoreFromEngineFunction 选项形成互补。
  • 修复:
    • monorepo 支持(#39005):此前在 monorepo 结构下构建会出错,1.2.0 起可正常工作;
    • Windows 上 handler 生成(#38900):修复路径分隔符导致的问题;
    • 补全 fetchRemoteFile 在 DSG/SSR 引擎中所需的 fs 方法重写(#38822);
    • 依赖升级:cookie ^0.6.0、fs-extra ^11.2.0。
  • 性能:adapt() 整体性能优化(#38988)。

1.3.0:动态路径误判修复(2025-08-27)

  • 修复"不要把时间戳当作动态路径"(#39340):带时间戳形态的路径(如含数字段的 URL)此前可能被误判为动态路由而触发不必要的重定向/文件移动,1.3.0 修正了判断逻辑。该修复先以补丁形式出现在 1.2.1(2025-08-05),随后合入 1.3.0。

1.4.0:Node 版本边界明确化(2026-01-26)

  • 使用更明确的 Node.js 版本范围(#39398):对应 package.json 中 engines: "node >=18.0.0 <26" 的声明,让依赖该适配器的用户能清晰判断运行环境的兼容区间。

常见疑问与排障线索

  • 本地调试:NETLIFY_LOCAL 环境变量下,缓存目录指向 .netlify/build-cache,deployURL 为 http://localhost:8888;CI 中则使用 /opt/build/cache 与 DEPLOY_URL(src/index.ts)。
  • 旧插件冲突:config() 返回的 pluginsToDisable 会自动禁用 gatsby-plugin-netlify-cache 与 gatsby-plugin-netlify,因为其能力已被适配器取代,无需再手动卸载。
  • 平台能力声明:supports.pathPrefix: true、supports.trailingSlash: ["always", "never", "ignore"]、functionsPlatform: "linux"、functionsArch: "x64"——这些声明决定了 Gatsby 核心对产物生成方式的处理策略。
  • 单测覆盖:包的 tests 目录下包含 lambda-handler、route-handler、pretty-urls、image-cdn-url-generator、file-cdn-url-generator 等测试文件,并带有 lambda-handler 的 fixture,可作为理解各模块输入输出契约的补充材料。

总结

gatsby-adapter-netlify 的价值在于把 Gatsby 与 Netlify 两套运行时模型之间的差异"翻译"干净:路由清单变成 _redirects/_headers,函数清单变成 Netlify Functions/Builders,远程资源变成 Image/File CDN。从 CHANGELOG 可以清晰看到它的演进脉络——先解决基础兼容(force/conditions、headerRoutes、大文件),再开启 CDN 与 pathPrefix,随后补齐 monorepo、Windows、datastore 等工程化场景,最后收敛 Node 版本边界。如果你正在 Netlify 上部署 Gatsby 站点,把 excludeDatastoreFromEngineFunction 与 imageCDN 按站点实际形态打开,配合正确的 netlify.toml 白名单,就能同时获得更小的函数包与更快的构建。

登录后查看全文
gatsby