Gatsby 配置 API
gatsby-config 定义了您站点的元数据、插件和其他常规配置。此文件应位于 Gatsby 站点的根目录中。您可以使用 JavaScript（CommonJS 或 ES Modules (ESM) 语法）或 TypeScript 来编写该文件，例如 gatsby-config.js、gatsby-config.mjs 或 gatsby-config.ts。
如果您使用 npm init gatsby 命令创建了 Gatsby 站点，则您的站点目录中应该已经有一个示例配置文件。注意： 在不同的 Gatsby 示例网站 中，有许多示例配置可能有助于参考。
设置配置文件
配置文件应导出一个 JavaScript 对象。在此对象中，您可以定义多个不同的配置选项。
一个示例 gatsby-config.js 文件可能如下所示
TypeScript 和 Gatsby 文档展示了如何设置 TypeScript 配置文件。
如果您不想使用 CommonJS 语法，请阅读 ES Modules (ESM) 和 Gatsby 文档。
配置选项
可以在 gatsby-config 中设置的选项包括
- siteMetadata (对象)
- plugins (数组)
- flags (对象)
- pathPrefix (字符串)
- trailingSlash (字符串)
- graphqlTypegen (布尔值)
- adapter (对象)
- headers (数组)
- polyfill (布尔值)
- mapping (对象)
- proxy (对象)
- developMiddleware (函数)
- jsxRuntime (字符串)
- jsxImportSource (字符串)
siteMetadata
当您希望在整个站点中重用常见数据（例如，您的站点标题）时，可以将该数据存储在 siteMetadata 中
这样您就可以在一个地方存储它，并在需要时随时提取。如果您需要更新信息，只需在此处更改即可。
在 Gatsby 教程第四部分 中查看完整描述和示例用法。
plugins
插件是实现 Gatsby API 的 Node.js 包。配置文件接受一个插件数组。有些插件可能只需要按名称列出，而另一些可能需要选项（请参阅各个插件的文档）。
使用 npm 等包管理器安装插件并不会在您的 Gatsby 站点中启用它。要完成添加插件，请确保您的 gatsby-config.js 文件有一个 plugins 数组，以便您可以为构建站点所需的插件腾出空间
添加多个插件时，为了支持有效的 JavaScript 语法，它们应该在 plugins 数组中用逗号分隔。
无选项插件
如果插件不需要任何选项，您可以将其名称作为字符串添加到 plugins 数组中
带选项插件
许多插件具有可选或必填选项来配置它们。而不是在 plugins 数组中添加名称字符串，而是添加一个包含其名称和选项的对象。大多数插件在其 README 文件或 Gatsby 插件库 的页面中显示示例。
这是一个示例，展示了如何编写一个带有 resolve 键来解析插件名称，以及一个带有任何适用设置的 options 对象的对象
混合插件
您可以在同一个数组中添加带选项和不带选项的插件。您的站点配置文件可以如下所示
有关更多利用插件的信息，以及查看可用的官方和社区插件，请参阅 插件。
flags
Flags 允许站点启用仍在测试中或等待下一个主版本发布的实验性或即将推出的更改。
pathPrefix
站点通常托管在其域的根目录之外。假设您的 Gatsby 站点位于 example.com/blog。在这种情况下，您需要在站点上的所有路径中添加一个前缀（/blog）。此选项的默认设置为 ""。
有关 添加路径前缀 的更多信息。
trailingSlash
支持添加于
gatsby@4.7.0
配置页面的 URL 创建，以及是否移除、添加或忽略尾部斜杠。
always：始终为每个 URL 添加尾部斜杠，例如将/x变为/x/。never：移除每个 URL 的所有尾部斜杠，例如将/x/变为/x。ignore：不自动修改 URL
此选项的默认设置为 always。Gatsby Cloud 会自动处理并支持 trailingSlash 选项。其他托管提供商（或如果您自己管理）应遵循 初始 RFC 中“重定向和托管提供商的预期行为”部分。
graphqlTypegen
支持添加于
gatsby@4.15.0
通过将 graphqlTypegen 设置为 true，您可以启用 GraphQL Typegen 功能。它将通过自动 TypeScript 类型生成和更好的 GraphQL IntelliSense，让您更轻松地将内容集成到页面中。
可选地，您可以通过将对象传递给 graphqlTypegen 来配置其行为，请参阅下面的选项。如果您不传递对象（但 graphqlTypegen: true），则每个选项的默认值将被使用。
typesOutputPath
支持添加于
gatsby@4.18.0
您可以指定相对于站点根目录的生成的 TypeScript 类型文件的路径。默认值：src/gatsby-types.d.ts。
documentSearchPaths
支持添加于
gatsby@5.3.0
您可以覆盖包含应扫描的文档的搜索路径。通常，您希望包含默认值并添加额外的路径。默认值：[`./gatsby-node.ts`, `./plugins/**/gatsby-node.ts`]。
generateOnBuild
支持添加于
gatsby@4.22.0
默认情况下，graphqlTypegen 仅在 gatsby develop 期间运行。将此选项设置为 true 也会在 gatsby build 期间创建 src/gatsby-types.d.ts 文件。默认值：false。
adapter
支持添加于
gatsby@5.12.0
您可以通过 adapter 设置来设置 适配器 或配置 零配置部署。
请阅读 适配器指南 以了解更多信息。
headers
支持添加于
gatsby@5.12.0
您可以为给定路径的响应设置自定义 HTTP 标头。
阅读 HTTP 标头指南 以了解更多关于标头语法、选项和行为的信息。
polyfill
Gatsby 使用 ES6 Promise API。因为一些浏览器不支持它，Gatsby 默认包含一个 Promise polyfill。
如果您想提供自己的 Promise polyfill，可以将 polyfill 设置为 false。
在 Gatsby 中有关 浏览器支持 的更多信息。
节点类型映射
请注意：我们强烈建议使用 @link GraphQL 指令。它支持更多用例，并且将来将是外键的首选方法。
Gatsby 包含一项功能，可让您在节点类型之间创建“映射”。
例如，想象一下您有一个多作者的 Markdown 博客，您想从每篇博文中“链接”到名为 author.yaml 的 YAML 文件中存储的作者信息
您可以通过将以下内容添加到 gatsby-config.js 来将 frontmatter 中的 author 字段映射到 author.yaml 对象中的 name
您可能需要安装适当的文件转换器（在此例中是 YAML）并正确设置 gatsby-source-filesystem，以便 Gatsby 能够识别映射文件。这同样适用于本节后面提到的其他文件类型。
Gatsby 然后在使用此映射创建 GraphQL 模式时，允许您查询这两个源的数据
映射还可以用于将 ID 数组映射到任何其他数据集合。例如，如果您有两个 JSON 文件 experience.json 和 tech.json，如下所示
然后将以下规则添加到您的 gatsby-config.js 中
您可以通过 experience 中引用的项目查询 tech 对象
映射也适用于 Markdown 文件。例如，您不必将所有作者都放在 YAML 文件中，而是可以将每个作者的信息放在单独的 Markdown 文件中
然后将以下规则添加到您的 gatsby-config.js 中
与 YAML 和 JSON 文件类似，Markdown 文件之间的映射也可以用于映射 ID 数组。
Proxy
设置 proxy 配置选项将指示开发服务器将任何未知请求代理到您指定的服务器。例如
有关 在开发中代理 API 请求 的更多信息。
使用 developMiddleware 进行高级代理
有关 添加开发中间件 的更多信息。
jsxRuntime
设置为 automatic 允许使用 JSX 而无需导入 React。有关更多信息，请参阅 Introducing the new JSX Transform 博客文章。
jsxImportSource
当 jsxRuntime 设置后，您可以使用 jsxImportSource 选择 React 使用哪个包作为底层的 JSX 转换器。例如，您可以将其设置为 @emotion/react，这样默认情况下将使用 @emotion/react 而不是 react 包。
请注意：目前您还需要在 babel-preset-gatsby 中设置此配置，请参阅 其 jsxImportSource 文档。