故障排除常见错误

当您在 Gatsby 中开发时遇到错误，很可能您会遇到其他用户已经遇到的问题。一些错误可能需要修复 Gatsby 的核心进程，最好将它们作为问题提交。您遇到的许多错误将意味着调整您如何配置网站中的插件或 API。

本指南旨在作为其他 Gatsby 用户遇到的常见错误参考。

缓存问题

在gatsby develop中运行站点会本地设置一个服务器，以启用热模块替换等功能。Gatsby 会将数据和渲染资源的缓存保存在 Gatsby 站点根目录的.cache文件夹中，这样它就不必重复处理优化资源的工作。如果您看到关于在缓存中找不到资源的错误，清除缓存并重新启动服务器可能就足够了。您可以通过运行以下命令来清除 Gatsby 的缓存：

这将为您删除.cache文件夹以及public文件夹。运行gatsby develop将重新创建缓存并再次处理所有资源。

您还可以参考关于调试缓存问题的专用指南。

有关缓存和持久化问题的更多讨论，请参阅汇总问题。

常见插件配置错误

插件扩展了 Gatsby 的功能，因为它们引入了新行为，所以安装的插件可能会引入错误。

安装样式插件导致 SSR 包生成失败

如果您在安装插件并尝试运行gatsby develop或gatsby build后遇到 webpack 错误，提示Generating SSR bundle failed，则可能是您尚未安装所有必需的包。

对于 emotion、styled-components 或 Sass 等一些插件，仅安装插件是不够的，您还需要安装它们依赖的库。官方安装说明应该能在您安装插件时引导您安装所有必需的库，但您在其他来源找到的一些教程或博客文章可能不会。

以下是一些需要您安装不止一个插件的示例：

• gatsby-plugin-emotion: @emotion/react 和 @emotion/styled
• gatsby-plugin-styled-components: styled-components 和 babel-plugin-styled-components
• gatsby-plugin-sass: node-sass 或 sass
• gatsby-plugin-material-ui: @material-ui/styles
• gatsby-plugin-image: gatsby-source-filesystem, gatsby-transformer-sharp, 和 gatsby-plugin-sharp

这些插件没有将其他依赖库打包在一起，而是保持了较小的体积，并且能够依赖替代实现。例如，gatsby-plugin-sass可以使用 Sass 的 Node.js 或 Dart 实现。

要解决这些错误，请确定尚未安装的软件包，错误消息可能如下所示：

此错误是由于在安装了 gatsby-plugin-emotion 并将其添加到 gatsby-config 后，未安装 emotion 库，导致 Gatsby 无法找到 @emotion/react。像这样安装它：

或者用缺失库的名称替换 @emotion/react。安装插件及所有必需库，并将插件添加到您的 gatsby-config 中，应可解决此错误。

fs 解析问题

您可能会看到此错误，因为您试图在 React 组件中使用 fs。此外，在使用 @mdx-js/runtime 时，通常会出现此错误。

此错误可能是顶层错误 Cannot resolve module 'fs'，也可能是 webpack 错误的一部分，例如 Can't resolve 'fs'。

fs 是 filesystem 的缩写，它是一个 Node.js 库，用于访问您计算机上的文件。但是，当您打包的 Gatsby 代码运行时，您的计算机已经是过去式了。

一些软件包，如 Babel，仍然会把 fs 带进来。为了防止它引起错误，您可以将以下内容添加到您的 gatsby-node.js 文件中。

样式错误

以下错误与您网站中的样式相关，包括 CSS、预处理器或 CSS-in-JS 解决方案。

使用 styled-components 或 emotion 在开发和构建之间 CSS 样式不一致

安装并开始使用 styled-components 或 emotion 的用户常遇到的问题是未在配置中包含相关插件。因为 gatsby develop 不运行服务器端渲染，如果未包含插件来告诉 Gatsby 为使用的 CSS-in-JS 解决方案进行服务器端渲染样式，则构建结果可能会有所不同。

将 gatsby-plugin-styled-components（对于 styled-components）或 gatsby-plugin-emotion（对于 emotion）添加到 gatsby-config.js 将会通知 Gatsby 进行服务器端样式处理，以便它们在最终构建中正确显示。

您可以在 gatsby-config 中使用 DEV_SSR 功能标志在 gatsby develop 期间启用 SSR 支持，这有助于您调试此类问题。

GraphQL 错误

Gatsby 的 GraphQL 数据层提供对构建时数据的访问，在实现数据源插件或自行向 schema 添加节点时，有时会遇到一些错误。

类型 'B' 上未知字段 'A'

如果您请求的数据与 GraphQL schema 中已源化的数据不同，您可能会遇到类似 Unknown field 'A' on type 'B' 的错误。正如错误提示的那样，您请求的字段在列出的类型下未定义。如果您的站点仍在正常构建，您可以打开 https://:8000/___graphql 来检查您的 schema，其中包含由错误提供的类型字段的定义。这可以帮助您确定哪些字段未被创建，并找到应创建这些字段的位置，无论是通过插件还是在您的代码中。

如果错误描述的是类型 Query 上的未知字段 'X'，那么您试图源化的内容类型可能未正确处理。Query 类型代表了 GraphQL schema 中包含的顶级根查询。源插件通常会创建您可以查询的根节点，例如 mdx（由 gatsby-plugin-mdx 创建）或一组根节点，例如 allFile（由 gatsby-source-filesystem 创建）。

调试这些错误的一些想法包括验证以下内容：

• 如果您使用的是转换器插件（例如 gatsby-transformer-yaml），则需要使用源插件（例如 gatsby-source-filesystem）来拉取所需数据。

• 您源化的内容结构与您的 GraphQL schema 以及您查询数据的方式相匹配。

将您的 GraphQL 查询与 https://:8000/___graphql 中的站点 schema 以及您用于源化数据的任何插件或代码进行比较，是查找这些错误的好方法，因为它们都应该以相同的形状表达数据。

• 您使用的任何源插件或您自己对sourceNodes API的实现都没有配置错误。

使用 gatsby-plugin-image 和 sharp 时出错

Gatsby 的图像处理被分解为不同的包，它们需要协同工作才能源化图像并将它们转换为不同的优化版本。您可能会在让它们协同工作时遇到这些错误。

字段“image”不得包含选择集，因为类型“String”没有子字段

这个错误消息 Field "image" must not have a selection since type "String" has no subfields. 出现时，GraphQL 查询试图查询字段的子字段，但不存在。这通常发生在一起使用的插件在 gatsby-config 中的顺序不正确，或者根本未添加时。

查询试图访问不存在的字段，因为它们在构建时未设置。在下面的代码中，查询试图查找 image 字段的子字段 childImageSharp，正如错误所说。有问题的 GraphQL schema 如下所示：

预期的 GraphQL schema 如下所示：

在第一个代码示例中，image 字段未被插件转换（修改）以添加子字段，因此它只会返回一个字符串。将 gatsby-plugin-sharp 和 gatsby-transformer-sharp 包含在其他可能会操作或创建图像节点的插件（如 gatsby-source-filesystem 或 gatsby-source-contentful）之前，可以确保在 Gatsby 尝试修改它们并添加 childImageSharp 等所需字段之前，它们是存在的。

您可以在关于处理外部图像的指南中阅读有关图像如何添加到 GraphQL schema 的更多信息。

导致此问题的另一个可能性是您的站点中某些地方的图像路径使用了空字符串。在这种情况下，当 Gatsby 构建 GraphQL schema 时，它可能会推断错误的类型，因为空字符串看起来不像文件路径。

使用 gatsby-plugin-sharp 安装 sharp 时出现问题 - gyp ERR! build error

如果您在安装依赖项时在控制台中看到与 sharp 相关的错误消息，例如 gyp ERR! build error 和 npm ERR! Failed at the sharp@x.x.x install script，通常可以通过删除项目根目录下的 node_modules 文件夹并重新安装依赖项来解决。

用于安装 sharp 的 Node.js 版本需要与运行它的 Node.js 版本匹配，因此清除 node_modules 并重新安装通常可以解决问题。

有关 sharp 安装和图像处理问题的更多讨论，请参阅此问题。

不兼容的库版本：sharp.node 需要 X 或更高版本，但 Y 提供了 Z 版本

错误 Incompatible library version: sharp.node requires version X or later, but Y provides version Z 意味着在 node_modules 中安装了多个不兼容的 sharp 包版本。您的错误可能看起来像这样：

为了解决这个问题，您需要更新项目中所有依赖 sharp 包的 Gatsby 插件。以下是如果您项目中使用了它们，可能需要更新的官方插件列表：

• gatsby-plugin-sharp
• gatsby-plugin-manifest
• gatsby-remark-images-contentful
• gatsby-source-contentful
• gatsby-transformer-sharp
• gatsby-transformer-sqip

要更新这些包，请运行：

如果更新这些插件不能解决问题，您的项目可能使用了来自社区的其他插件，它们依赖于不同版本的 sharp。尝试运行 npm list sharp 或 yarn why sharp 来查看项目中所有使用 sharp 的包，并尝试更新它们。

构建和部署错误

构建站点的过程与开发过程略有不同。如果您在构建站点时包含对浏览器的引用，可能会出现一些错误，尽管几乎所有问题都应该在 develop 模式下的错误消息中捕获。

有关构建站点时常见问题的更多信息，请参阅调试 HTML 构建指南。

运行 gatsby build 时出现错误：ReferenceError: window is not defined

如果您在代码中引用了浏览器全局变量（如 window 或 document），则可能会遇到在开发时未出现的错误，例如 Error: ReferenceError: window is not defined。由于构建不是在浏览器中运行的，它将无法访问浏览器，这就是为什么 window 等对象未定义的原因。

有关修复此问题的确切步骤，请参阅调试 HTML 构建指南中关于检查 window 是否已定义的部分。

来自字段“browser”不包含有效别名配置的构建问题

如果您看到类似以下错误：

构建无法找到文件 ../..SomeFile.svg。如果您的站点在本地使用 gatsby develop 运行时工作正常，甚至在本地运行 gatsby build 和 gatsby serve 时也能工作，这可能会令人沮丧。一个可能的问题是，您本地使用的操作系统与您的站点部署到的操作系统不同。通常，您的部署目标运行的是某个 Linux 发行版和版本。

最常见的导致此问题的罪魁祸首是文件路径的大小写混合。在上面的例子中，请确保文件实际命名为 SomeFile.svg，而不是其他名称，例如 Somefile.svg 或 somefile.svg。某些操作系统会为您识别这种差异并毫无问题地找到图像。您的部署环境可能不会。

检查构建日志中输出文件的文件名大小写并重新部署是下一步的最佳选择。

错误：ENOSPC：系统文件监视器数量限制已达到

您可能遇到了系统对可监视文件数量的限制。

要解决此问题，请使用以下命令增加系统的文件监视器限制（即在您的站点运行时，检查文件更改的进程数量）：

您可以在与此错误相对应的 GitHub issue中找到更多关于您具体情况的信息。