WPGraphQL for ACF 字段映射

解决的问题

Headless WordPress 中，WPGraphQL 默认不会暴露 Advanced Custom Fields（ACF）的字段组、重复字段（Repeater）或自定义文章类型元数据。开发者要么手动编写自定义 REST 端点，要么在 GraphQL 查询里硬编码字段逻辑，导致接口分散、类型不一致，后续维护成本高。

技能如何工作

该技能通过扩展 WPGraphQL，将 ACF 的数据结构映射为类型化的 GraphQL schema。核心能力包括：

• 字段组映射：将 ACF 字段组中的字段，转换为 GraphQL 的 Fields，支持字符串、数字、关系等常见类型。
• 复杂字段支持：对 Repeater、Flexible Content 等 ACF 高级字段，生成可迭代的 GraphQL 类型，避免手动处理嵌套结构。
• 元数据查询：自定义文章类型的元数据可直接通过 GraphQL 查询，无需额外接口。

使用时，需确保环境已安装 WPGraphQL（推荐最新版）和 ACF（Free 或 PRO），可选安装 ACF Extended（Free 或 PRO）以支持更多字段类型。

适用边界与注意点

• 依赖版本：建议使用 WPGraphQL 和 ACF 的最新版本，旧版本可能存在字段映射不全或类型冲突的问题。
• ACF Extended 非必需：仅在需要使用其扩展字段（如 Group Field、Repeater 的高级选项）时安装，否则不影响基础功能。
• Headless 场景适配：适合前后端分离的 WordPress 项目，传统 WP 主题开发中无需使用该技能。