无头WordPress能否兼容Gutenberg与ACF块？求可靠JS前端方案

一、核心技术栈选型 #

• 前端框架：优先推荐Next.js（对WP生态适配更成熟，动态内容处理更顺畅），也可修复你此前的Gatsby配置问题
• WordPress端必备插件：
  • WPGraphQL：官方原生GraphQL接口插件，自动支持Gutenberg块数据暴露
  • WPGraphQL for Advanced Custom Fields：适配ACF字段及ACF自定义块
  • 确保WP默认启用Gutenberg编辑器

二、WordPress端配置步骤 #

1. 安装并激活WPGraphQL与WPGraphQL for Advanced Custom Fields插件
2. 进入ACF设置面板，在「WPGraphQL」标签页中，勾选「Expose ACF Fields to GraphQL」，同时确保所有需要的ACF块（含灵活内容块）的「Show in GraphQL」选项为开启状态
3. Gutenberg原生块无需额外配置，WPGraphQL会自动将文章/页面的blocks数据纳入GraphQL查询范围

三、前端实现方案（两种路径） #

路径1：修复Gatsby配置问题 #

你此前遇到的块数据缺失、插件报错，大概率是版本冲突或配置遗漏：

• 卸载第三方graphQL Gutenberg插件，改用gatsby-source-wordpress@^6.x稳定版，该版本原生支持WPGraphQL块数据
• 在gatsby-config.js中配置WP源时，明确开启块数据拉取：

  module.exports = {
    plugins: [
      {
        resolve: `gatsby-source-wordpress`,
        options: {
          url: `https://你的WP站点域名/graphql`,
          schema: { timeout: 60000 },
          type: { Post: { limit: 100 } },
          // 指定需要拉取的块类型，可按需添加
          includeBlocks: ["core/paragraph", "core/image", "acf/你的自定义块"],
        },
      },
    ],
  };
  

• 查询GraphQL时，直接从post.content.blocks获取块数据，ACF块的自定义字段会嵌套在attributes.acf对象中

路径2：改用Next.js实现（更稳定） #

1. 可使用graphql-request直接调用WPGraphQL接口，或借助@wpengine/headless简化开发
2. 示例GraphQL查询（获取文章及对应块数据）：

   query GetPost($id: ID!) {
     post(id: $id, idType: SLUG) {
       title
       blocks {
         name
         attributes
         innerBlocks
       }
     }
   }
   

3. 块渲染核心逻辑：
   • 遍历blocks数组，根据name字段匹配对应组件（如core/paragraph对应Paragraph组件，acf/hero-banner对应自定义HeroBanner组件）
   • ACF块的自定义字段从attributes.acf中提取，传入对应组件
   • 嵌套块（innerBlocks）通过递归渲染处理

四、通用块渲染组件封装 #

无论用Gatsby还是Next.js，都可封装统一的BlockRenderer组件简化开发：

import Paragraph from "./blocks/Paragraph";
import Image from "./blocks/Image";
import CustomACFBlock from "./blocks/CustomACFBlock";

const BLOCK_COMPONENTS = {
  "core/paragraph": Paragraph,
  "core/image": Image,
  "acf/custom-acf-block": CustomACFBlock,
};

const BlockRenderer = ({ blocks }) => {
  return blocks.map((block, index) => {
    const Component = BLOCK_COMPONENTS[block.name];
    if (!Component) return null;

    return (
      <Component
        key={index}
        attributes={block.attributes}
        innerBlocks={block.innerBlocks}
      />
    );
  });
};

export default BlockRenderer;

后续新增块只需在BLOCK_COMPONENTS中添加对应组件即可。

内容的提问来源于stack exchange，提问作者H_G