Gatsby Adapter 机制深入解析:gatsby-adapter-netlify 的版本演进、配置选项与源码实现
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() 可以看到一次适配的四个步骤:
- 若启用了
imageCDN,先调用handleAllowedRemoteUrlsNetlifyConfig校验netlify.toml白名单; - 调用
prepareFileCdnHandler生成 File CDN 边缘函数(Edge Function)与清单; - 调用
handleRoutesManifest(routesManifest, headerRoutes)处理路由:生成_redirects/_headers并把静态文件移动到漂亮 URL(pretty URL)位置,同时返回"使用缓存(ODB)的 Lambda 名映射"; - 遍历
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转换成 Nodereq/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 白名单,就能同时获得更小的函数包与更快的构建。