使用ACF创建的Gutenberg Block（block.json）在页面编辑器中不可见

按照教程使用ACF创建Gutenberg区块，配置如下，但区块在页面编辑器中不可见，且无PHP或JS错误，请求排查原因。

配置代码 #

block.json #

{       
    "name"           : "quick-links",
    "title"         : "Quick Links",
    "apiVersion"    : 2,
    "icon"          : "admin-users",
    "mode"          : "auto",
    "acf": {
        "mode": "preview",
        "renderTemplate": "quick-links.php"
    },
    "align"         : "full",
    "keywords"      : [ "Quick-Links", "Links" ]
}

插件注册代码 #

<?php
/**
 * Plugin Name: Gutenberg Block
 * Description: Blocks to display photo/video galleries, quicklinks, downloads, ... 
 * Version: 1.0
 */
add_action( 'init', 'register_acf_blocks', 5 );
function register_acf_blocks() {

register_block_type( __DIR__ . '/blocks/quick-links/block.json' );
}

渲染文件 quick-links.php #

仅输出一段字符串（如<?php echo 'Hello Quick Links'; ?>）

• 确认ACF Pro已激活：ACF区块功能仅支持ACF Pro版本，免费版无此功能，需确保插件已安装并正常启用。
• 校验文件路径：检查插件目录结构是否正确，block.json需位于插件根目录/blocks/quick-links/下，注册代码中__DIR__指向插件主文件所在目录，需保证路径指向准确。
• 修正区块名称规范：WordPress要求区块name字段必须包含命名空间前缀（格式为命名空间/区块名，例如my-plugin/quick-links），无命名空间的名称可能导致注册失败。
• 检查WordPress版本兼容性：apiVersion: 2对应WordPress 5.8及以上版本，若你的WordPress版本过低，需升级WP或将apiVersion改为1。
• 调整预览模式配置：acf.mode: preview要求渲染模板能生成有效预览内容，若quick-links.php存在隐性语法问题，可能导致区块无法显示。可临时将acf.mode改为edit，测试是否能看到区块框架。
• 强制刷新编辑器缓存：在Gutenberg编辑器页面按Ctrl+Shift+R强制刷新，清除编辑器缓存，确保新注册的区块被加载。
• 验证区块注册状态：添加调试代码确认区块是否成功注册：

  add_action('init', function() {
      $registered_blocks = WP_Block_Type_Registry::get_instance()->get_all_registered();
      var_dump(array_keys($registered_blocks));
  });
  

  执行后查看输出，确认目标区块名称是否在已注册列表中，判断注册流程是否正常。

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