部署适配器

概述

Gatsby 部署适配器提供了一个框架，用于针对特定托管平台优化 Gatsby 网站的部署。该系统支持平台特定的优化、配置和功能实现，同时在不同的托管环境中保持一致的开发者体验。

Gatsby v5.12.0 中引入的适配器系统允许 Gatsby 生成特定于平台的部署构件，而无需开发人员手动配置特定于平台的设置。这提供了跨各种托管平台的更无缝的部署体验。

有关已部署网站性能优化策略的信息，请参阅性能优化。

架构

适配器系统被设计为可插拔和可扩展的，允许不同的托管提供商创建自己的适配器，以与 Gatsby 实现最佳集成。

来源： packages/gatsby/package.json220

核心概念

适配器系统组件

Gatsby 的部署适配器系统包含几个协同工作的关键组件。

来源： packages/gatsby/package.json220

适配器清单

适配器系统使用清单文件来跟踪适配器与不同 Gatsby 版本的兼容性。这确保了与每个 Gatsby 版本都能使用正确的适配器版本。

配置

基本配置

要使用部署适配器，请将其添加到您的 Gatsby 配置文件中。

可用适配器

目前，主要支持的适配器是 gatsby-adapter-netlify，它针对 Netlify 平台优化 Gatsby 网站的部署。

零配置体验

Gatsby 提供零配置体验，可以自动检测部署环境并应用适当的适配器。这通过托管平台提供的环境变量来处理。

来源： packages/gatsby/CHANGELOG.md32 packages/gatsby/CHANGELOG.md33

适配器支持的功能

重定向

适配器可以将 Gatsby 的重定向定义转换为特定于平台的重定向配置。这包括支持：

强制重定向（状态码 301 vs 302）
基于国家/地区、角色、Cookie 存在情况等的条件重定向。
重定向路径中的模式匹配和参数

来源： packages/gatsby/CHANGELOG.md127

自定义标头

适配器可以为不同的路由生成自定义 HTTP 标头，将 Gatsby 的标头定义转换为特定于平台的配置。

来源： packages/gatsby/CHANGELOG.md128

CDN URL 生成

自 v5.13.0 起，适配器可以为图像和文件生成自定义 CDN URL，根据托管平台的性能优化资源交付。

来源： packages/gatsby/CHANGELOG.md120

无服务器函数

适配器可以将 Gatsby 的 API 函数（用于服务器端渲染和延迟静态生成）转换为特定于平台的无服务器函数。

与 Gatsby 构建系统的集成

适配器系统已集成到 Gatsby 的构建过程中，并与几个关键子系统进行交互。

来源： packages/gatsby/CHANGELOG.md131

错误处理

适配器系统包含错误处理机制，可防止在使用所选适配器不支持的功能时导致构建失败。Gatsby 不会失败构建，而是会发出不支持功能的警告并继续构建过程。

来源： packages/gatsby/CHANGELOG.md131 packages/gatsby/CHANGELOG.md195

路径处理

适配器支持路径前缀和尾部斜杠选项，以确保在不同的部署环境中一致地处理 URL。

来源： packages/gatsby/CHANGELOG.md162

Netlify 适配器示例

gatsby-adapter-netlify 适配器是最全功能的适配器，它提供了与 Netlify 平台功能的集成。

来源： packages/gatsby/CHANGELOG.md125

缓存和性能优化

适配器可以为不同类型的路由优化缓存策略，从而提高网站性能。

来源： packages/gatsby/CHANGELOG.md95

最佳实践

在使用 Gatsby 部署适配器时

尽可能使用零配置，让 Gatsby 自动检测并配置部署环境的适配器。
检查兼容性：确保您的 Gatsby 版本与适配器版本兼容，以保证最佳兼容性。
注意平台限制：并非所有 Gatsby 功能都可能得到每个平台适配器的支持。
查看适配器日志：在构建过程中查看日志，以捕获关于不支持功能或配置问题的警告。

故障排除

常见问题

适配器兼容性问题：确保您的适配器版本与 Gatsby 版本兼容。适配器清单有助于管理这种兼容性。
```
// Example error message
The installed version of gatsby-adapter-netlify is not compatible with your version of Gatsby.
```
功能支持警告：如果您使用的功能不受所选适配器的支持，Gatsby 会发出警告但继续构建。
```
// Example warning message
The selected adapter does not support custom cache headers. Using default settings.
```
路径处理不一致：如果您遇到路径处理问题，请检查您的 trailingSlash 和 pathPrefix 设置。