WordPress顶级短代码内容无法自动添加段落标签问题排查

问题现象 #

• 短代码在行内嵌入段落时，内容能正常被<p>标签包裹
• 短代码单独占一行时，返回内容会绕过WordPress自动段落机制，丢失<p>标签，导致样式异常

测试环境 #

使用极简短代码复现问题：

/**
 * 仅返回包裹内容的短代码
 */
function do_echo_shortcode( $args, $content ): string {
    return $content;
}
add_shortcode( 'echo', 'do_echo_shortcode' );

测试步骤与异常输出 #

在WYSIWYG编辑器中输入：

This is a paragraph

[echo]This is also one[/echo]

But here's an [echo]echo[/echo] inside a paragraph!

前端生成的异常HTML：

<p>This is a paragraph</p>
This is also one
<p>But here’s an echo inside a paragraph!</p>

可见单独成行的短代码内容未被<p>标签包裹。

若修改短代码为返回apply_filters( 'the_content', $content )：

return apply_filters( 'the_content', $content );

则会破坏行内短代码的正常结构，生成的HTML变为：

<p>This is a paragraph</p>
<p>This is also one</p>

<p>But here’s an </p><p>echo</p>
inside a paragraph!<p></p>

调试信息 #

通过挂载the_content过滤器调试，未手动添加过滤器时，内容处理流程中的关键值如下：

1. <p>This is a paragraph</p>\n <p>But here&#8217;s an inside a paragraph!</p>\n
2. This is also one
3. echo
4. <p>This is a paragraph</p>\nThis is also one\n<p>But here&#8217;s an echo inside a paragraph!</p>\n

解决方案 #

核心思路是判断短代码的上下文（行内/单独成行），针对性处理段落包裹：

方案1：通过全局过滤上下文判断 #

function do_echo_shortcode( $args, $content ): string {
    global $wp_current_filter;
    
    // 检测短代码是否处于the_content主过滤流程（单独成行场景）
    if ( in_array( 'the_content', $wp_current_filter, true ) ) {
        // 单独成行时应用自动段落处理
        return wpautop( $content );
    }
    
    // 行内场景直接返回内容
    return $content;
}
add_shortcode( 'echo', 'do_echo_shortcode' );

方案2：通过原始内容位置判断上下文 #

function do_echo_shortcode( $args, $content, $tag ): string {
    global $post;
    $full_content = $post->post_content;
    
    // 匹配短代码在原始内容中的位置
    $pattern = get_shortcode_regex();
    preg_match_all( "/$pattern/", $full_content, $matches, PREG_OFFSET_CAPTURE );
    
    foreach ( $matches[0] as $match ) {
        if ( $match[0] === "[echo]$content[/echo]" ) {
            $pos = $match[1];
            // 检查短代码前后是否为换行，判断是否单独成行
            $prev_char = $pos > 0 ? substr( $full_content, $pos - 1, 1 ) : '';
            $next_char = substr( $full_content, $pos + strlen( $match[0] ), 1 );
            
            if ( ( $prev_char === "\n" || $prev_char === '' ) && ( $next_char === "\n" || $next_char === '' ) ) {
                return wpautop( $content );
            }
        }
    }
    
    return $content;
}
add_shortcode( 'echo', 'do_echo_shortcode' );

预期正确输出 #

应用上述方案后，前端将生成符合要求的HTML：

<p>This is a paragraph</p>
<p>This is also one</p>
<p>But here’s an echo inside a paragraph!</p>

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