WordPress图片标题追加文本失败，代码无报错求排查

你的两段代码失效的原因如下：

1. 第一段代码：str_replace无法匹配目标字符串
   WordPress生成的caption输出是完整的HTML结构（比如<figure><figcaption>原标题</figcaption></figure>），原caption文本可能被HTML转义、或者前后存在空格/换行，导致直接用$attr['caption']作为替换关键词无法找到匹配项，因此追加文本不会生效。

2. 第二段代码：文本追加位置错误
   直接将文本追加到$output末尾，会把内容放在整个图片容器（<figure>）的外部，而非<figcaption>标签内部，因此不会显示在图片标题区域。

正确实现方案 #

方案一：重构Caption HTML（推荐，兼容性好）

直接利用短码参数重新生成完整的caption结构，避免字符串替换的不确定性：

add_filter('img_caption_shortcode', 'modify_caption_text', 10, 3);
function modify_caption_text($output, $attr, $content) {
    // 设置参数默认值
    $attr = shortcode_atts([
        'id'      => '',
        'align'   => 'alignnone',
        'width'   => '',
        'caption' => ''
    ], $attr);

    // 无标题或宽度无效时返回原输出
    if (empty($attr['caption']) || !$attr['width']) {
        return $output;
    }

    // 构建带追加文本的新标题
    $new_caption = $attr['caption'] . ' <em>- Custom Text</em>';

    // 处理ID属性
    $id_attr = !empty($attr['id']) ? 'id="' . esc_attr($attr['id']) . '" ' : '';

    // 生成完整的caption HTML
    return sprintf(
        '<figure %sclass="wp-caption %s" style="width: %dpx">%s<figcaption class="wp-caption-text">%s</figcaption></figure>',
        $id_attr,
        esc_attr($attr['align']),
        (int)$attr['width'],
        do_shortcode($content),
        $new_caption
    );
}

方案二：用DOM操作修改标题内容

适合不想重构HTML的场景，通过DOM解析精准修改<figcaption>内部内容：

add_filter('img_caption_shortcode', 'append_image_credit_to_caption', 10, 3);
function append_image_credit_to_caption($output, $attr, $content) {
    if (empty($attr['caption'])) {
        return $output;
    }

    $additional_text = ' <em>- Custom Text</em>';

    // 解析HTML内容
    $dom = new DOMDocument();
    $dom->loadHTML(mb_convert_encoding($output, 'HTML-ENTITIES', 'UTF-8'));
    $figcaptions = $dom->getElementsByTagName('figcaption');

    if ($figcaptions->length > 0) {
        // 创建并追加新内容节点
        $additional_node = $dom->createDocumentFragment();
        $additional_node->appendXML($additional_text);
        $figcaptions->item(0)->appendChild($additional_node);

        // 提取修改后的HTML
        $output = $dom->saveHTML($dom->getElementsByTagName('figure')->item(0));
    }

    return $output;
}

针对Gutenberg块编辑器的补充 #

如果使用的是块编辑器（而非经典编辑器短码），需要额外处理图片块的输出：

add_filter('render_block', 'modify_gutenberg_image_caption', 10, 2);
function modify_gutenberg_image_caption($block_content, $block) {
    // 仅处理图片块
    if ($block['blockName'] !== 'core/image') {
        return $block_content;
    }

    $additional_text = ' <em>- Custom Text</em>';

    $dom = new DOMDocument();
    $dom->loadHTML(mb_convert_encoding($block_content, 'HTML-ENTITIES', 'UTF-8'));
    $figcaptions = $dom->getElementsByTagName('figcaption');

    if ($figcaptions->length > 0) {
        $additional_node = $dom->createDocumentFragment();
        $additional_node->appendXML($additional_text);
        $figcaptions->item(0)->appendChild($additional_node);
        $block_content = $dom->saveHTML($dom->getElementsByTagName('figure')->item(0));
    }

    return $block_content;
}

注意事项 #

• 将代码添加到当前主题的functions.php文件，或自定义插件中
• 测试前请清空WordPress缓存，避免旧输出影响结果

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