自定义文章类型(CPT)区块模板前端不显示问题求助

核心配置检查 #

首先确保你的register_post_type()函数里包含以下关键参数——这是Gutenberg模板生效的基础：

• 开启REST API支持：'show_in_rest' => true，Gutenberg依赖该参数读取和保存区块数据
• 启用编辑器支持：'supports' => array('editor', 'title', 'thumbnail')，必须包含editor才能加载区块编辑器

正确的Template参数写法 #

确认你的template格式完全符合WordPress要求，示例代码如下：

register_post_type('book', array(
    'labels' => array(
        'name' => '书籍',
        'singular_name' => '书籍'
    ),
    'public' => true,
    'show_in_rest' => true,
    'supports' => array('editor', 'title', 'thumbnail'),
    'template' => array(
        // 图片区块
        array('core/image', array(
            'align' => 'center',
            'placeholder' => '上传书籍封面'
        )),
        // 标题区块
        array('core/heading', array(
            'level' => 2,
            'placeholder' => '输入书籍副标题'
        )),
        // 段落区块
        array('core/paragraph', array(
            'placeholder' => '输入书籍简介'
        ))
    ),
    'template_lock' => 'all' // 可选：锁定模板结构，用户仅能编辑内容，无法修改区块顺序/删除
));

前端无内容的排查 #

如果编辑后台能看到模板结构，但前端显示空白，检查以下两点：

• 主题模板文件：若使用自定义的single-book.php或single-book.html（块主题），确保文件正确调用内容输出逻辑：
  • PHP模板需添加：

    if (have_posts()) :
        while (have_posts()) : the_post();
            the_content();
        endwhile;
    endif;
    

  • 块主题的HTML模板需包含<!-- wp:post-content /-->标签，WordPress会自动替换为文章内容。
• 检查内容保存状态：编辑文章时，哪怕使用模板，也需至少对某个区块做编辑（如输入文字、上传图片）再发布，空模板可能无法被正确保存到数据库。

额外注意事项 #

• 避免同时使用可复用区块和CPT模板，防止触发Gutenberg的关联问题
• 测试时禁用所有非必要插件，排除插件冲突
• 确保WordPress版本在5.8以上，Gutenberg模板功能在该版本后才稳定支持

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