WordPress自动输出HowTo结构化数据：从零实现富媒体展示

在搜索结果中，你是否见过带有步骤、图片，甚至视频的“操作指南”卡片？这就是 HowTo 结构化数据 带来的魔力。它能让你的教程类内容直接以醒目的富媒体形式展现，大幅提升点击率。但对于 wordpress 站长来说，如果每篇教程都要手动粘贴 JSON-LD 代码，效率低且容易出错。本文将教你如何自动输出 HowTo 结构化数据，无需每篇重复劳动，写完文章即可被搜索引擎识别。

1. 什么是 HowTo 结构化数据？

HowTo 是 Schema.org 定义的一种标记类型，专用于“如何做某事”的指导性内容，例如食谱、DIY 教程、维修指南等。正确部署后，Google 会在搜索结果中直接展示步骤条、所需材料、工具和预估时间，让你的页面脱颖而出。

要在 WordPress 中实现自动输出，最稳定的方法是借助自定义字段，动态生成 JSON-LD 代码，并挂载到页面的 <head> 区域。下面将详述两种主流方案：使用高级自定义字段（ACF）以及纯代码解析法。

2. 方案一：基于 ACF 的完全自动化（推荐）

适用场景：你有固定的教程结构，希望内容录入直观、输出完全受控。
所需工具：Advanced Custom Fields (ACF) 或类似自定义字段插件。

2.1 创建自定义文章类型（可选）

为教程类内容建立一个独立的内容类型（如 tutorial），管理起来更清爽。将以下代码加入主题 functions.php：

function create_tutorial_post_type() {
    register_post_type('tutorial',
        array(
            'labels'      => array('name' => __('教程')),
            'public'      => true,
            'has_archive' => true,
            'supports'    => array('title', 'editor', 'thumbnail'),
            'show_in_rest'=> true, // 启用古腾堡编辑器
        )
    );
}
add_action('init', 'create_tutorial_post_type');

2.2 配置 ACF 字段组

在后台自定义字段中新建一个字段组，绑定到 tutorial 文章类型，包含以下字段：

教程简介 (howto_description)：文本区域，用于简短描述。
预估时间 (howto_total_time)：文本，如“PT30M”（ISO 8601 时长格式）。
所需物料 (howto_supply)：中继器，内含 name（物料名称）。
所需工具 (howto_tool)：中继器，内含 name（工具名称）。
步骤 (howto_steps)：中继器，内含：
- step_title（文本）
- step_description（文本区域或编辑器）
- step_image（图片，返回图片ID或URL）

设置完成后，当撰写新教程时，界面会类似：

[教程简介]：如何更换自行车内胎，零基础也能学会... [预估时间]：PT20M [所需物料] 重复添加：新内胎、撬胎棒 [所需工具] 重复添加：打气筒 [步骤] 步骤1：移除车轮 - 描述... - [上传图片] 步骤2：撬出外胎 - 描述... - [上传图片] ...

2.3 编写 JSON-LD 生成函数

在 functions.php 中写入核心逻辑，仅当正在显示单个教程文章时输出结构化数据：

function generate_howto_schema() {
    if ( ! is_singular('tutorial') ) return;
    
    global $post;
    $description = get_field('howto_description', $post->ID);
    $total_time  = get_field('howto_total_time', $post->ID);
    $supplies    = get_field('howto_supply', $post->ID);
    $tools       = get_field('howto_tool', $post->ID);
    $steps       = get_field('howto_steps', $post->ID);

    // 如果没有步骤，则退出
    if ( empty($steps) ) return;

    $schema = [
        '@context'    => 'https://schema.org',
        '@type'       => 'HowTo',
        'name'        => get_the_title($post),
        'description' => $description ?: '',
        'totalTime'   => $total_time ?: '',
        'supply'      => [],
        'tool'        => [],
        'step'        => [],
    ];

    // 处理物料
    if ( $supplies ) {
        foreach ( $supplies as $item ) {
            $schema['supply'][] = ['@type' => 'HowToSupply', 'name' => $item['name']];
        }
    }

    // 处理工具
    if ( $tools ) {
        foreach ( $tools as $item ) {
            $schema['tool'][] = ['@type' => 'HowToTool', 'name' => $item['name']];
        }
    }

    // 处理步骤，生成有序数组
    $step_counter = 1;
    foreach ( $steps as $step ) {
        $step_data = [
            '@type' => 'HowToStep',
            'position' => $step_counter,
            'name' => $step['step_title'],
            'itemListElement' => [
                [
                    '@type' => 'HowToDirection',
                    'text' => $step['step_description'],
                ]
            ]
        ];

        // 如果设置了步骤图片，加入 image 属性
        if ( ! empty($step['step_image']) ) {
            $img_url = wp_get_attachment_url($step['step_image']);
            if ( $img_url ) {
                $step_data['image'] = $img_url;
            }
        }

        $schema['step'][] = $step_data;
        $step_counter++;
    }

    // 输出为 JSON-LD 脚本
    echo '<script type="application/ld+json">' . json_encode($schema, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE) . '</script>';
}
add_action('wp_head', 'generate_howto_schema', 5);

代码逻辑清晰：收集字段数据 → 组装 Schema.org 数组 → json_encode → 以标准的 <script> 标签输出。JSON_UNESCAPED_UNICODE 确保中文字符不会被转为 \u 编码。

2.4 验证与微调

发布一篇测试教程，使用 Google 富媒体搜索结果测试工具或 Schema Markup Validator 检测。确保每个步骤都完整，无必填字段缺失（如 text）。若要求视频，也可以扩展字段并在代码中添加 video 属性。

3. 方案二：自动从文章内容解析步骤（轻量级）

如果你不想安装 ACF，也可以根据文章中的标题标签自动拆解步骤。比如规定使用二级标题（h2）作为步骤名，紧跟的段落为步骤说明。
此方法的优点是零额外插件，但结构自由度低，不便于添加图片、物料等细粒度信息。

function parse_content_howto_schema() {
    if ( ! is_single() ) return;  // 应用于所有文章，或限定特定分类

    global $post;
    $content = $post->post_content;
    
    // 使用正则匹配 <h2> 标题和后续内容（直到下一个 h2 或结尾）
    preg_match_all('/<h2[^>]*>(.*?)<\/h2>(.*?)(?=<h2|$)/si', $content, $matches, PREG_SET_ORDER);
    
    if ( count($matches) < 2 ) return; // 至少两个步骤才生成

    $steps = [];
    $position = 1;
    foreach ( $matches as $match ) {
        $step_title = strip_tags($match[1]);
        $step_desc  = wp_strip_all_tags($match[2]); // 去除HTML，取纯文本
        $step_desc  = trim(preg_replace('/\s+/', ' ', $step_desc)); // 压缩空格
        
        if ( empty($step_title) || empty($step_desc) ) continue;
        
        $steps[] = [
            '@type' => 'HowToStep',
            'position' => $position,
            'name' => $step_title,
            'itemListElement' => [
                ['@type' => 'HowToDirection', 'text' => $step_desc]
            ]
        ];
        $position++;
    }

    if ( empty($steps) ) return;

    $schema = [
        '@context'   => 'https://schema.org',
        '@type'      => 'HowTo',
        'name'       => get_the_title(),
        'step'       => $steps,
    ];

    echo '<script type="application/ld+json">' . json_encode($schema, JSON_UNESCAPED_UNICODE) . '</script>';
}
add_action('wp_head', 'parse_content_howto_schema');

局限性：无法自动捕获总时长、工具、物料，也无法为步骤添加图片。且如果文章内 h2 含有非步骤类标题（如“注意事项”），会被错误纳入，需额外增加判断。

4. 使用 SEO 插件半自动输出

主流的 SEO 插件也已内置 HowTo 模块，但仍需手动填写：

Rank Math：在编辑文章时切换到“Schema”选项卡，选择“HowTo”，填入步骤、所需物料等。它会在对应页面自动输出 JSON-LD。
Yoast SEO（Premium）：通过内容块添加结构化数据，有 HowTo 块可以直接拖拽使用。
Schema Pro：配置一次模板，即可让特定文章类型自动应用 HowTo 标记，类似于 ACF 但无需写代码。

这类工具适合非技术用户，但“自动”仅限于模板化生成，初始设定仍需逐项定义。对于追求完全无感自动化的开发者，前两种代码方案更为灵活。

5. 常见问题与调试

5.1 如何提供 ISO 8601 时长？

格式为 PT 开头，后接小时（H）、分钟（M）。例如：

1小时30分 → PT1H30M
15分钟 → PT15M
2小时 → PT2H

在 ACF 中可以添加提示文本辅助编辑。

5.2 图片不显示或验证报错

步骤图片属性建议用 image（字符串URL），Google 也支持 ImageObject。确保 wp_get_attachment_url 获取到正确 URL，并且图片可公开访问。

5.3 页面出现多重输出

如果你的主题或插件也添加了结构化数据，可能会冲突。请检查页头源代码，保证只有一份 HowTo 标记。必要时可通过 remove_action 清除。

5.4 步骤描述中需要保留 HTML 吗？

itemListElement.text 应为纯文本。如需更丰富的格式，可使用 HowToDirection 的 text 或 description 属性，部分富媒体结果支持有限的 HTML 标签，但为了最大兼容性，建议提供干净文本。

6. 扩展：为 AMP 和移动端优化

如果你的站点启用了 AMP 插件，WordPress 的 wp_head 钩子同样有效。只需确保输出的 JSON-LD 在 <head> 中即可。移动端富媒体展示与桌面端无异，但图片尺寸需合适（1200px 宽以上为佳），以适配横向步骤卡片。

结语

通过自定义字段配合几行 PHP 代码，WordPress 就能够全自动输出 HowTo 结构化数据。你只需专注撰写教程内容，系统自动在页面渲染出搜索引擎喜爱的标记。无论是提升点击率，还是抢占语音助手回答，这都是一项值得投入的 SEO 技术。赶紧动手试试，让你的教程内容在搜索结果中“动”起来吧！

微言心语