核心概念

相关源文件

• integration-tests/artifacts/__tests__/index.js
• integration-tests/artifacts/gatsby-node.js
• integration-tests/artifacts/src/components/react-lazily-imported.js
• integration-tests/artifacts/src/pages/react-lazy.js
• packages/gatsby/cache-dir/__tests__/__snapshots__/dev-loader.js.snap
• packages/gatsby/cache-dir/__tests__/__snapshots__/loader.js.snap
• packages/gatsby/cache-dir/__tests__/dev-loader.js
• packages/gatsby/cache-dir/__tests__/find-path.js
• packages/gatsby/cache-dir/__tests__/loader.js
• packages/gatsby/cache-dir/app.js
• packages/gatsby/cache-dir/dev-loader.js
• packages/gatsby/cache-dir/find-path.js
• packages/gatsby/cache-dir/gatsby-browser-entry.js
• packages/gatsby/cache-dir/loader.js
• packages/gatsby/cache-dir/production-app.js
• packages/gatsby/cache-dir/query-result-store.js
• packages/gatsby/index.d.ts
• packages/gatsby/src/bootstrap/requires-writer.ts
• packages/gatsby/src/commands/build-html.ts
• packages/gatsby/src/commands/build-utils.ts
• packages/gatsby/src/commands/build.ts
• packages/gatsby/src/commands/develop-process.ts
• packages/gatsby/src/datastore/__tests__/nodes.js
• packages/gatsby/src/query/index.ts
• packages/gatsby/src/query/query-runner.ts
• packages/gatsby/src/redux/__tests__/__snapshots__/index.js.snap
• packages/gatsby/src/redux/__tests__/__snapshots__/nodes.ts.snap
• packages/gatsby/src/redux/__tests__/index.js
• packages/gatsby/src/redux/__tests__/nodes.ts
• packages/gatsby/src/redux/actions/add-page-dependency.ts
• packages/gatsby/src/redux/actions/internal.ts
• packages/gatsby/src/redux/actions/public.js
• packages/gatsby/src/redux/index.ts
• packages/gatsby/src/redux/persist.ts
• packages/gatsby/src/redux/reducers/__tests__/__snapshots__/queries.ts.snap
• packages/gatsby/src/redux/reducers/__tests__/queries.ts
• packages/gatsby/src/redux/reducers/components.ts
• packages/gatsby/src/redux/reducers/config.ts
• packages/gatsby/src/redux/reducers/html.ts
• packages/gatsby/src/redux/reducers/index.ts
• packages/gatsby/src/redux/reducers/last-action.ts
• packages/gatsby/src/redux/reducers/nodes-by-type.ts
• packages/gatsby/src/redux/reducers/nodes-touched.ts
• packages/gatsby/src/redux/reducers/nodes.ts
• packages/gatsby/src/redux/reducers/page-data-stats.ts
• packages/gatsby/src/redux/reducers/queries.ts
• packages/gatsby/src/redux/types.ts
• packages/gatsby/src/services/build-schema.ts
• packages/gatsby/src/services/calculate-dirty-queries.ts
• packages/gatsby/src/services/create-pages.ts
• packages/gatsby/src/services/customize-schema.ts
• packages/gatsby/src/services/extract-queries.ts
• packages/gatsby/src/services/index.ts
• packages/gatsby/src/services/initialize.ts
• packages/gatsby/src/services/listen-for-mutations.ts
• packages/gatsby/src/services/post-bootstrap.ts
• packages/gatsby/src/services/run-mutation-batch.ts
• packages/gatsby/src/services/run-page-queries.ts
• packages/gatsby/src/services/run-static-queries.ts
• packages/gatsby/src/services/source-nodes.ts
• packages/gatsby/src/services/start-webpack-server.ts
• packages/gatsby/src/services/types.ts
• packages/gatsby/src/services/write-out-redirects.ts
• packages/gatsby/src/services/write-out-requires.ts
• packages/gatsby/src/state-machines/__tests__/develop.ts
• packages/gatsby/src/state-machines/__tests__/query-running.ts
• packages/gatsby/src/state-machines/data-layer/actions.ts
• packages/gatsby/src/state-machines/data-layer/index.ts
• packages/gatsby/src/state-machines/data-layer/services.ts
• packages/gatsby/src/state-machines/data-layer/types.ts
• packages/gatsby/src/state-machines/develop/actions.ts
• packages/gatsby/src/state-machines/develop/index.ts
• packages/gatsby/src/state-machines/develop/services.ts
• packages/gatsby/src/state-machines/query-running/actions.ts
• packages/gatsby/src/state-machines/query-running/index.ts
• packages/gatsby/src/state-machines/query-running/services.ts
• packages/gatsby/src/state-machines/query-running/types.ts
• packages/gatsby/src/state-machines/waiting/actions.ts
• packages/gatsby/src/state-machines/waiting/index.ts
• packages/gatsby/src/state-machines/waiting/types.ts
• packages/gatsby/src/utils/__tests__/__snapshots__/handle-flags.ts.snap
• packages/gatsby/src/utils/__tests__/__snapshots__/show-experiment-notice.js.snap
• packages/gatsby/src/utils/__tests__/batcher.ts
• packages/gatsby/src/utils/__tests__/get-page-data.ts
• packages/gatsby/src/utils/__tests__/handle-flags.ts
• packages/gatsby/src/utils/__tests__/page-data.ts
• packages/gatsby/src/utils/__tests__/show-experiment-notice.js
• packages/gatsby/src/utils/__tests__/websocket-manager.ts
• packages/gatsby/src/utils/batcher.ts
• packages/gatsby/src/utils/call-deferred-api.ts
• packages/gatsby/src/utils/create-schema-customization.ts
• packages/gatsby/src/utils/flags.ts
• packages/gatsby/src/utils/gatsby-dependents.ts
• packages/gatsby/src/utils/get-page-data.ts
• packages/gatsby/src/utils/handle-flags.ts
• packages/gatsby/src/utils/page-data-helpers.ts
• packages/gatsby/src/utils/page-data.ts
• packages/gatsby/src/utils/show-experiment-notice.ts
• packages/gatsby/src/utils/start-server.ts
• packages/gatsby/src/utils/state-machine-logging.ts
• packages/gatsby/src/utils/webpack/get-ssr-chunk-hashes.ts
• packages/gatsby/src/utils/websocket-manager.ts
• packages/gatsby/src/utils/worker/child/render-html.ts

本页面解释了 Gatsby 的基本概念，包括其架构、数据模型、构建过程和渲染策略。有关仓库结构的信息，请参见仓库结构。有关插件生态系统的详细信息，请参见插件生态系统。

架构概述

Gatsby 是一个现代的 Web 框架，它结合了 React、GraphQL 和 webpack 的最佳部分，以创建具有动态功能的静态站点。其核心是，Gatsby 遵循独特的架构，处理来自各种来源的数据，将其转换为统一的数据层，并生成优化的静态资产。

来源：packages/gatsby/index.d.ts1-247 packages/gatsby/src/redux/types.ts1-170 packages/gatsby/src/commands/build.ts1-100

数据层

Gatsby 的数据层是一个强大的抽象，它将来自各种来源的数据整合到一个统一的 GraphQL API 中。这个数据层是 Gatsby 构建页面以及实现从站点任何位置查询数据的核心。

节点模型

Gatsby 数据层的基础是节点模型。“节点”是 Gatsby 中数据的基本单位，代表着从博客文章到图片再到站点元数据的一切。

节点的主要特征

• 每个节点都有一个唯一的 ID
• 节点可以通过父/子关系引用其他节点
• 节点有一个内部对象，其中包含类型和内容摘要等元数据
• contentDigest 属性使 Gatsby 能够高效地跟踪更改
• 节点在数据源阶段由源插件创建

来源：packages/gatsby/index.d.ts147-162 packages/gatsby/src/redux/types.ts147-162 packages/gatsby/src/redux/actions/public.js596-713

Redux 状态管理

Gatsby 内部使用 Redux 来管理构建过程的状态。这个状态存储包含构建过程中使用的所有节点、页面和其他重要数据。

Gatsby 中的 Redux 存储包括

• 节点及其关系
• 页面、组件和静态查询
• GraphQL 模式和查询结果
• 配置和程序状态
• Webpack 编译状态

来源：packages/gatsby/src/redux/index.ts1-120 packages/gatsby/src/redux/types.ts279-449 packages/gatsby/src/redux/persist.ts1-44

GraphQL 层

Gatsby 的 GraphQL 层位于节点模型之上，提供了一种查询语言来访问您的数据。在构建过程中，Gatsby 根据您的数据创建 GraphQL 模式，并使其可用于查询。

Gatsby 中的主要 GraphQL 概念

• 页面查询（Page Queries）：与特定页面绑定并可以接受变量的查询
• 静态查询（Static Queries）：可以在任何组件中使用但不能接受变量的查询
• 模式定制（Schema Customization）：明确定义和定制 GraphQL 模式的 API
• 字段扩展（Field Extensions）：用于修改字段解析数据方式的自定义指令

来源：packages/gatsby/index.d.ts315-328 packages/gatsby/src/query/query-runner.ts1-93 packages/gatsby/src/redux/types.ts366-379

页面生成模型

Gatsby 支持多种页面生成策略，允许开发者根据每个页面的需求选择合适的方法。

页面模式

Gatsby 支持三种主要的页面生成模式

1. 静态站点生成（SSG）：默认模式。页面在构建时预渲染为 HTML。

   • 为最终用户提供最快的性能
   • 内容在构建时生成
   • 非常适合不经常更改的内容

2. 延迟静态生成（DSG）：页面在首次请求时构建，然后为后续访问者缓存。

   • 在 createPage() 中设置为 defer: true
   • 通过延迟低流量页面实现更快的构建
   • 首次访问者加载时间稍慢

3. 服务器端渲染（SSR）：页面在每次请求时渲染。

   • 通过导出 getServerData() 函数启用
   • 允许请求时数据获取
   • 非常适合个性化或高度动态的内容

来源：packages/gatsby/src/redux/types.ts43-69 packages/gatsby/src/redux/actions/public.js140-204 packages/gatsby/src/utils/page-mode.ts

构建流程

Gatsby 的构建过程将您的代码和数据转换为优化的静态站点。了解此过程有助于您优化站点的性能和开发工作流程。

构建过程包括以下主要阶段

1. 引导阶段（Bootstrap Phase）：加载配置和插件，设置 Redux 存储
2. 数据源阶段（Data Sourcing Phase）：从外部系统获取节点，并对其进行转换
3. 页面生成阶段（Page Generation Phase）：创建页面，提取 GraphQL 查询
4. Webpack 编译阶段（Webpack Compilation Phase）：编译 JavaScript 和 CSS 资产
5. HTML 生成阶段（HTML Generation Phase）：渲染 HTML 页面并生成数据文件

来源：packages/gatsby/src/commands/build.ts72-175 packages/gatsby/src/services/initialize.ts76-147 packages/gatsby/src/commands/build-html.ts30-211

查询执行

在构建过程中，Gatsby 执行 GraphQL 查询以填充页面数据

查询执行的关键方面

• 使用 babel 插件从您的代码中提取查询
• Gatsby 跟踪哪些查询是“脏的”需要重新运行
• GraphQL 运行器针对 GraphQL 模式执行查询
• 结果存储在 JSON 文件中供客户端使用

来源：packages/gatsby/src/query/query-runner.ts93-222 packages/gatsby/src/utils/page-data.ts100-167 packages/gatsby/src/commands/build.ts286-350

客户端运行时

构建过程完成后，Gatsby 生成一个在浏览器中运行的 React 应用程序，以提供交互性和客户端导航。

客户端运行时的关键组件

• 页面加载器（Page Loader）：按需加载页面数据和 JavaScript 块
• Gatsby Link：提供预取功能并管理客户端导航
• 静态查询结果（Static Query Results）：使静态查询结果可用于组件
• 页面资源（Page Resources）：管理页面数据和组件的加载和缓存

来源：packages/gatsby/cache-dir/production-app.js1-143 packages/gatsby/cache-dir/loader.js1-165 packages/gatsby/cache-dir/app.js1-207

API 和扩展点

Gatsby 提供了一套丰富的 API 和扩展点，用于自定义构建过程和运行时行为。

节点 API

节点 API 允许您连接到 Gatsby 的服务器端构建过程

API	目的	执行计时
onPreBootstrap	引导过程前的设置	构建开始时
sourceNodes	从外部数据创建节点	数据源阶段
onCreateNode	转换节点或创建关系	每个节点创建后
createSchemaCustomization	定制 GraphQL 模式	模式生成前
createPages	从数据创建页面	数据源后
onCreatePage	修改插件创建的页面	每个页面创建后
onCreateWebpackConfig	修改 webpack 配置	webpack 编译前
onPostBuild	构建完成后的最终操作	构建结束时

浏览器API

浏览器 API 允许您自定义 Gatsby 的客户端运行时

API	目的	执行计时
onClientEntry	客户端加载时运行代码	客户端加载开始时
onRouteUpdate	在路由更改时运行代码	导航后
onServiceWorkerInstalled	处理 Service Worker 事件	Service Worker 安装后
wrapPageElement	用组件包装页面	渲染期间
wrapRootElement	包装根元素	渲染期间

来源：packages/gatsby/index.d.ts402-733 packages/gatsby/index.d.ts743-801

页面组件和查询

Gatsby 页面是 React 组件，可以选择包含在构建过程中获取数据的 GraphQL 查询。

页面组件的关键概念

• 页面组件（Page Components）：在特定路由定义页面的 React 组件
• 页面查询（Page Queries）：为特定页面获取数据的 GraphQL 查询
• 静态查询（Static Queries）：可以在任何组件中使用的 GraphQL 查询
• Head 组件（Head Components）：作为 Head 导出的特殊组件，用于定义文档头部内容
• Slice 组件（Slice Components）：带有自己 GraphQL 查询的可复用组件

页面结构示例

来源：packages/gatsby/index.d.ts70-107 packages/gatsby/index.d.ts175-203 packages/gatsby/index.d.ts243-268

开发与生产

Gatsby 在开发和生产环境中具有不同的行为

功能	开发	生产
页面生成	按需	全部在构建时
服务器	本地开发服务器	静态文件服务器
热重载	已启用	不适用
GraphQL IDE	在 /__graphql 可用	不可用
构建优化	最小	完全优化
页面模式	所有 SSG 以提高速度	基于配置的 SSG、DSG 或 SSR
错误覆盖	交互式与源映射	不可用

开发服务器提供多项功能以增强开发体验

• React 组件的热模块替换
• 快速刷新以在编辑期间保留组件状态
• 用于查询测试的 GraphQL Playground
• 带有可操作错误消息的错误覆盖层

来源：packages/gatsby/src/utils/start-server.ts67-145 packages/gatsby/src/commands/develop-process.ts1-152 packages/gatsby/cache-dir/app.js70-206

结论

Gatsby 的核心概念围绕着强大的数据层、灵活的页面生成策略以及基于 React 的组件系统。该框架结合了静态站点生成的最佳特性和动态功能，在提供卓越性能的同时保持了开发人员的体验。

通过理解这些核心概念，您将能够有效地使用 Gatsby 来处理各种 Web 项目，从简单的博客到复杂的应用程序。

来源：packages/gatsby/index.d.ts packages/gatsby/src/redux/types.ts packages/gatsby/src/commands/build.ts packages/gatsby/cache-dir/production-app.js