本文档解释了 Gatsby 的结构化错误处理系统，该系统为开发者提供清晰、可操作的错误消息。该系统旨在标准化整个 Gatsby 生态系统中错误的报告、格式化和显示方式。
有关 CLI 及其命令的信息，请参阅 CLI 和命令。
Gatsby 实现了一个复杂的错误处理系统，该系统将原始错误转换为具有一致格式、分类和文档链接的结构化、信息丰富的错误对象。
来源：packages/gatsby-cli/src/structured-errors/error-map.ts1-1649 packages/gatsby-cli/src/structured-errors/construct-error.ts1-66 packages/gatsby-cli/src/structured-errors/error-schema.ts1-49 packages/gatsby-cli/src/reporter/reporter.ts1-373
Gatsby 使用结构化错误格式，提供一致、详细的错误信息。此格式包含错误代码、文档链接、分类和其他元数据，以帮助开发者理解和解决问题。
来源：packages/gatsby-cli/src/structured-errors/types.ts1-112 packages/gatsby-cli/src/structured-errors/construct-error.ts1-66 packages/gatsby-cli/src/structured-errors/error-schema.ts1-49
当 Gatsby 中发生错误时，它会通过 constructError 函数进行处理，该函数根据提供的错误详情和错误映射创建一个标准化的错误对象。然后，构建的错误会根据模式进行验证，以确保其遵循预期的格式。
来源：packages/gatsby-cli/src/structured-errors/construct-error.ts14-63
错误映射是 Gatsby 中所有错误类型的中央注册表。它将错误代码映射到定义错误格式和显示方式的模板。映射中的每个条目都包含错误文本（作为模板函数）、级别、类别、类型和可选的文档 URL。
错误映射允许 Gatsby 为已知错误类型提供一致、信息丰富的错误消息。它还允许插件使用 setErrorMap 方法注册自己的自定义错误类型。
来源：packages/gatsby-cli/src/structured-errors/error-map.ts23-950 packages/gatsby-cli/src/reporter/reporter.ts69-74
Reporter 模块是报告 Gatsby 中的错误、警告、信息和活动的核心接口。它提供了创建和报告结构化错误的方法，以及跟踪活动及其进度的方法。
| 方法 | 描述 | 用例示例 |
|---|---|---|
error | 报告错误 | 报告配置错误 |
panic | 报告错误并退出进程 | 阻止 Gatsby 继续执行的致命错误 |
panicOnBuild | 在构建模式下报告错误并退出 | 构建特定的错误 |
warn | 报告警告 | 可能不会导致执行停止的问题 |
info | 报告信息性消息 | 状态更新 |
verbose | 报告详细消息（仅在启用了详细模式时） | 详细的调试信息 |
activityTimer | 创建活动计时器 | 跟踪长时间运行的操作 |
createProgress | 创建进度条 | 具有可量化进度的操作 |
来源：packages/gatsby-cli/src/reporter/reporter.ts106-315
来源：packages/gatsby-cli/src/reporter/reporter.ts129-202 packages/gatsby-cli/src/reporter/redux/internal-actions.ts86-149
Gatsby 插件既可以产生错误，也可以处理错误。API 运行器会包装插件的执行，并捕获插件抛出的任何错误，将它们转换为结构化错误。
来源：packages/gatsby/src/utils/api-runner-node.js632-707
插件可以通过使用 Reporter 上的 setErrorMap 方法来定义自己的自定义错误类型。这允许插件提供具有自定义错误代码、消息和文档链接的专用错误处理。
为确保插件的错误代码不会与核心 Gatsby 错误代码冲突，在报告插件错误代码时，它们会被加上插件名称的前缀。
来源：packages/gatsby-cli/src/reporter/reporter.ts69-74 packages/gatsby/src/utils/api-runner-node.js199-212 packages/gatsby/src/utils/__tests__/fixtures/api-runner-node/test-plugin-activity-map/gatsby-node.js1-17
Gatsby 包含一个诊断系统，可以检测活动何时卡住并提供调试信息。这有助于识别和解决 Gatsby 可能挂起或需要太长时间才能完成任务的问题。
诊断系统会监控活动及其进度。如果活动长时间停留在 InProgress 状态，Gatsby 可以提供诊断信息，甚至终止进程以防止无限期挂起。
此诊断系统可以使用环境变量进行配置
GATSBY_DIAGNOSTIC_STUCK_STATUS_TIMEOUT：设置诊断警告的超时时间GATSBY_WATCHDOG_STUCK_STATUS_TIMEOUT：设置进程终止的超时时间来源：packages/gatsby-cli/src/reporter/redux/diagnostics.ts67-218 packages/gatsby-cli/src/reporter/redux/internal-actions.ts54-84
Gatsby 的错误处理系统提供了一个强大的框架，用于以一致、信息丰富的方式创建、处理和报告错误。通过使用结构化错误和集中的错误映射，Gatsby 确保开发者收到清晰、可操作的错误消息，帮助他们快速识别和解决问题。
该系统与插件的集成使得整个 Gatsby 生态系统能够受益于相同的错误处理功能，无论错误是源自核心 Gatsby 代码还是第三方插件，都能提供一致的体验。
来源：packages/gatsby-cli/src/structured-errors/error-map.ts1-1649 packages/gatsby-cli/src/reporter/reporter.ts1-373 packages/gatsby/src/utils/api-runner-node.js632-707