企业官网建设流程全解析

在 Gatsby 中使用 Advanced Custom Fields：gatsby-source-wordpress 与 WPGraphQL for ACF 完整实战指南

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby

Advanced Custom Fields（ACF）是 WordPress 生态中最流行的自定义字段插件，本指南基于gatsby-source-wordpress官方教程，完整演示如何将 ACF Field Group 暴露到 WPGraphQL Schema，再通过 Gatsby 的 GraphQL API 查询 ACF 数据。读完本文，你将掌握 ACF Field Group 的 GraphQL 配置方法、WPGraphQL 与 Gatsby 两套查询的写法差异，以及 gatsby-source-wordpress 底层如何通过 Schema 合并自动继承 WPGraphQL 扩展数据。

前置条件

本教程假设你已经搭建好一个可运行的 Gatsby 站点：gatsby-source-wordpress已激活，并指向一个由 WPGraphQL，了解数据在两端之间如何流动。

在开始之前，你还需要：

• 一个可用的 WordPress 实例，并已安装激活 WPGraphQL 与 WPGatsby 两个必需插件（详见 安装与快速开始）；
• 在gatsby-config.js中将gatsby-source-wordpress的url配置指向 WordPress 的 GraphQL 端点，例如https://yoursite.com/graphql；
• 安装免费的 Advanced Custom Fields 插件，以及免费的WPGraphQL for Advanced Custom Fields（wp-graphql-acf）WordPress 插件。

什么是 Advanced Custom Fields？

Advanced Custom Fields（简称 ACF）是一款 WordPress 插件，它允许开发者通过图形化界面构建表单，在 WordPress 后台为文章、页面、自定义文章类型等对象编辑额外内容。ACF 并非创建自定义字段的唯一选择，但它是最流行的方案之一，并且拥有与 WPGraphQL 的官方集成，因此成为 Gatsby 站点从 WordPress 获取结构化扩展数据的首选路径。

让 ACF 字段进入 WPGraphQL Schema

WPGraphQL for ACF 是 WPGraphQL 的官方扩展插件。安装并激活它之后，你便可以在 ACF 的 Field Group 设置中，决定该字段组是否（以及以什么名字）出现在 WPGraphQL Schema 中。

官方文档同时将WPGraphQL for Advanced Custom Fields列在“已确认可用的 WPGraphQL 扩展”清单中（见 与主流 WPGraphQL 扩展的配合使用），即该扩展产出的数据已被 gatsby-source-wordpress 在生产站点中验证可用。

为什么 ACF 数据能自动被 Gatsby 使用？

gatsby-source-wordpress 之所以能“无感”继承 ACF 数据，源于其核心的 Schema 合并机制。从源码看，该插件首先通过 GraphQL introspection 拉取 WordPress 端完整的 Schema 副本：

• 在 introspect-remote-schema.js 中，introspectAndStoreRemoteSchema向 WordPress 的 GraphQL 端点发送introspectionQuery，将返回结果按${pluginOptions.url}--introspection-data作为键写入持久化缓存；
• 在 create-schema-customization/index.js 中，插件遍历 introspection 得到的__schema.types，把其中“被实际拉取过数据”（fieldOfTypeWasFetched）且未被排除（typeIsExcluded）的 Object、Interface、Union、Enum 类型，逐一构建为 Gatsby 侧对应的 GraphQL Type。

这意味着：只要 WPGraphQL for ACF 往 WPGraphQL Schema 中注册了新的字段或类型，它们就会出现在 introspection 结果里，从而被 gatsby-source-wordpress 自动复制到 Gatsby 的 Schema 中。正如 GraphQL、WordPress 与 Gatsby 所述：“任何 WPGraphQL 扩展都会自动成为一个 Gatsby Source 插件”——ACF 只是其中一个典型的例子。

实战示例：配置一个 ACF Field Group 并查询数据

下面我们完整走一遍“在 WordPress 后台创建 ACF 字段组 → 暴露到 GraphQL → 在 WPGraphQL 查询 → 在 Gatsby 查询”的流程。

第一步：创建 ACF Field Group

ACF 提供了可视化的字段组配置界面。在 WordPress 后台进入“自定义字段 → 字段组 → 添加新字段组”，然后：

1. 命名 Field Group 为Test Post Fields；
2. 添加一个Text（文本框）字段，字段名为text_field；
3. 设置Location Rules为 “Post Type is equal to Post”，使该字段组仅出现在文章编辑页。

第二步：将 Field Group 暴露到 GraphQL

在 Field Group 设置底部，ACF 提供了与 GraphQL 相关的两个配置项：

发布该 Field Group 后：

• ACF 会把该字段组挂载到 Post 编辑屏幕；
• WPGraphQL for ACF 会根据 Location Rules 推断，把testPostFields这个字段注册到 GraphQL Schema 的Post类型上。

第三步：在文章中写入 ACF 数据

接下来编辑一篇文章，你会看到 “Test Post Fields” 字段组出现在编辑页面上。在 “Text Field” 中输入Test field value...并保存，数据即写入 WordPress。

第四步：用 WPGraphQL 验证查询

打开 WordPress 后台的 GraphiQL IDE，用下面的查询验证字段是否可查（示例中文章的数据库 ID 为2068）：

{ post(id: 2068, idType: DATABASE_ID) { id title testPostFields { textField } } }

注意 WPGraphQL 侧使用的是post(id: 2068, idType: DATABASE_ID)这种“服务端过滤参数”写法，这是 WPGraphQL 与 Gatsby GraphQL API 的重要差异之一。

第五步：在 Gatsby 中查询 ACF 字段

现在切换到 Gatsby 侧。启动gatsby develop后，打开 Gatsby 的 GraphiQL 界面（开发服务器默认在http://localhost:8000/___graphql），使用同样的 ACF 字段查询：

{ wpPost(databaseId: { eq: 2068 }) { id title testPostFields { textField } } }

查询成功返回testField value...，说明 ACF 数据已经被 gatsby-source-wordpress 拉取进 Gatsby 的 Node 层，前端可以直接基于该字段构建页面或组件。

理解 WPGraphQL 与 Gatsby 查询的差异

从上面的两条查询可以看出，同一份 ACF 数据在两端有着不同的查询语法。根据 GraphQL、WordPress 与 Gatsby 的说明，两者主要有以下区别：

• Schema 前缀：gatsby-source-wordpress 会为来自 WPGraphQL 的类型加上Wp前缀（可通过 plugin options 中的schema.typePrefix修改），因此 WPGraphQL 的Post在 Gatsby 中是WpPost；
• 连接命名：Gatsby 用all前缀表示节点列表，WPGraphQL 的根字段post/posts在 Gatsby 中对应wpPost/allWpPost；
• 查询参数：WPGraphQL 的输入参数（如idType: DATABASE_ID）会直接影响服务端返回结果；而 Gatsby 查询的是本地 Node 层，输入参数是 Gatsby 的过滤器语法（如databaseId: { eq: 2068 }），两者并不等价，查询时不能混用。

提示：两套 Schema 的差异比较细微，建议同时使用 WordPress 后台 GraphiQL 和 Gatsby GraphiQL 熟悉各自的字段与参数。

在 Gatsby 页面中使用 ACF 数据

ACF 字段进入 Gatsby 的 Node 层之后，就可以像使用任何 Gatsby 数据一样使用它。例如在页面查询（Page Query）中获取 ACF 字段：

query PostPage($id: String!) { wpPost(id: { eq: $id }) { id title testPostFields { textField } } }

然后在 React 组件中读取data.wpPost.testPostFields.textField渲染即可。由于 gatsby-source-wordpress 在构建期间已经把 WordPress 数据完整复制到 Gatsby 的 Node 层（详见 数据抓取流程 与 introspect-remote-schema.js），页面渲染时不会再有额外的网络请求回源到 WordPress。

进阶：扩展类型的注意事项

ACF 的 Text 等标量字段（Scalar）在 Gatsby 中“开箱即用”。但如果某个 WPGraphQL 扩展暴露的不只是标量字段，而是 Node 和 Connection（如 ACF 的关系字段、重复字段组等更复杂的结构），则该扩展应遵循 GraphQL Relay 规范才能真正与 gatsby-source-wordpress 良好协作：

• Node 应能通过 Root Query 独立查询，同时也能作为连接的一部分从类型 A 关联到类型 B；
• 层级数据（如父子关系）应尽量以扁平列表返回，并提供parentId/parentDatabaseId字段。

满足这些约束后，gatsby-source-wordpress 才能正确地把关联节点链接到 Gatsby 侧对应的 Node 上，而不是重复拉取数据。

小结

通过 WPGraphQL for ACF 这座桥梁，ACF 的字段组可以一键进入 WPGraphQL Schema，并借助 gatsby-source-wordpress 的 introspection + Schema 合并机制自动出现在 Gatsby 的 GraphQL API 中。整个链路无需编写额外的 Gatsby 插件或 PHP 代码，只需在 WordPress 后台完成 Field Group 的创建与 “Show in GraphQL” 配置，即可在 Gatsby 中查询并渲染 ACF 数据。相关源码与文档可供继续深入：教程原文见 using-advanced-custom-fields.md，Schema 合并原理见 features/graphql-wordpress-and-gatsby.md，源码实现见 src/steps/ingest-remote-schema/introspect-remote-schema.js 与 src/steps/create-schema-customization/index.js。

【免费下载链接】gatsbyReact-based framework with performance, scalability, and security built in.项目地址: https://gitcode.com/gh_mirrors/ga/gatsby