ACF 自定义字段 REST 暴露器

要解决的问题

WordPress 的 REST API 默认只返回文章和分类法等核心数据，Advanced Custom Fields（ACF） 通过元数据或文章数据表存储的自定义字段不会自动出现在响应里。这意味着前端如果想用 fetch 直接读取一篇书中的作者、简介或封面图，要么自己拼凑 ACF 的读取逻辑，要么绕道别的方式取数，开发成本和出错概率都不低。

技能如何工作

这个技能的核心思路是利用 WordPress 的扩展点：

• 用 register_rest_field 在 REST 响应中挂载自定义字段数据；
• 用 acf_format_value 在返回前对 ACF 原始值做格式化，而不是直接吐出数据库里的存储结构；
• 针对 重复字段（Repeater）、灵活内容布局（Flexible Content） 和 图库字段（Gallery） 分别做序列化处理，保证 JSON 结构稳定、前端可直接消费。

以资料中的示例为例：先注册一个自定义文章类型 book，并配置包含作者（文本）、作者简介（WYSIWYG）、作者图像（图像）的字段组。之后对 REST 端点发起 OPTIONS 请求，即可查看数据对象的 schema，确认各 ACF 字段及其属性已正确暴露。

适用边界与注意点

• POST 请求允许更新任意 ACF 字段，必须做好身份验证，否则等于开放了后台数据的写入入口；
• 灵活内容和重复字段的嵌套结构较深，序列化策略需要与前端约定清楚；
• 该技能是对 ACF 官方 REST API 集成方案的封装，复杂字段类型仍可能需要额外的格式化逻辑。

参考文档：Advanced Custom Fields 官方的 WP REST API integration 指南。