2026年7月27日

WordPressのショートコードが動かない・表示されない問題を解決する方法

カスタマイズ

はじめに

WordPressのショートコードが[my_shortcode]のままテキストとして表示される場合、登録タイミングのミス・ウィジェットでの未対応・ブロックエディターとの非互換が主な原因です。

症状・原因

ショートコードがテキストとして[shortcode_name]のまま表示される
ウィジェットエリアやカスタムフィールドでショートコードが実行されない
特定のページだけショートコードが動かない
ブロックエディターで追加したショートコードが機能しない

解決手順

ステップ1：ショートコードの登録状態を確認する

# 登録済みショートコードを確認
wp eval "
global \$shortcode_tags;
foreach (array_keys(\$shortcode_tags) as \$tag) {
    echo \$tag . PHP_EOL;
}
" | grep -i my_shortcode

# ショートコードを直接実行してテスト
wp eval "echo do_shortcode('[my_shortcode id=\"1\"]');"

# functions.php の構文チェック
php -l wp-content/themes/my-theme/functions.php

ステップ2：ショートコードを正しく登録する

// functions.php: ショートコードを正しく登録

// ① 基本的なショートコード
add_shortcode('my_shortcode', function(array $atts, ?string $content = null): string {
    // デフォルト値とユーザー指定値をマージ
    $atts = shortcode_atts([
        'id'    => 0,
        'style' => 'default',
        'title' => '',
    ], $atts, 'my_shortcode');

    $id    = absint($atts['id']);
    $style = sanitize_key($atts['style']);
    $title = sanitize_text_field($atts['title']);

    // コンテンツが囲み型の場合
    $inner = $content ? do_shortcode($content) : '';

    ob_start();
    ?>
    <div class="my-shortcode my-shortcode--<?php echo esc_attr($style); ?>">
        <?php if ($title): ?>
            <h3><?php echo esc_html($title); ?></h3>
        <?php endif; ?>
        <?php echo wp_kses_post($inner); ?>
    </div>
    <?php
    return ob_get_clean();
});

// ② ショートコードの登録解除（プラグインのものを上書きする場合）
add_action('init', function(): void {
    remove_shortcode('old_shortcode');
    add_shortcode('old_shortcode', 'my_replacement_callback');
}, 20); // プラグインより後に実行

ステップ3：ウィジェット・カスタムフィールドでショートコードを有効にする

// functions.php: テキストウィジェットでショートコードを有効化
// WordPress 4.9以降はデフォルトで有効だが、念のため
add_filter('widget_text', 'do_shortcode');
add_filter('widget_text_content', 'do_shortcode');

// カスタムフィールド（ACF等）でショートコードを実行
add_filter('acf_the_field', 'do_shortcode');

// the_excerpt でショートコードを実行
add_filter('the_excerpt', 'do_shortcode');

// カスタム投稿メタでショートコードを実行
function get_meta_with_shortcode(int $post_id, string $key): string {
    $value = get_post_meta($post_id, $key, true);
    return do_shortcode((string) $value);
}

// 任意の文字列でショートコードを手動実行
$output = do_shortcode('[my_shortcode id="5" title="テスト"]コンテンツ[/my_shortcode]');
echo $output;

ステップ4：ブロックエディターでショートコードを使う

// functions.php: ブロックエディターでのショートコードブロック対応
// Gutenbergでは「ショートコード」ブロックを使うが、
// カスタムブロックからショートコードを呼び出す場合

// REST API でショートコードを処理してレスポンスに含める
add_filter('rest_prepare_post', function(WP_REST_Response $response, WP_Post $post): WP_REST_Response {
    $data = $response->get_data();
    if (isset($data['content']['rendered'])) {
        $data['content']['rendered'] = do_shortcode($data['content']['rendered']);
        $response->set_data($data);
    }
    return $response;
}, 10, 2);

// ショートコードをブロックとして登録（推奨）
add_action('init', function(): void {
    if (!function_exists('register_block_type')) {
        return;
    }
    register_block_type('my-plugin/my-shortcode', [
        'render_callback' => function(array $attributes): string {
            return do_shortcode('[my_shortcode id="' . absint($attributes['id'] ?? 0) . '"]');
        },
        'attributes' => [
            'id' => ['type' => 'integer', 'default' => 0],
        ],
    ]);
});

ステップ5：ショートコードのデバッグと出力確認

// functions.php: ショートコードのデバッグ
add_shortcode('debug_shortcode', function(array $atts): string {
    if (!current_user_can('administrator')) {
        return '';
    }

    global $shortcode_tags;
    $registered = array_keys($shortcode_tags);
    sort($registered);

    $output = '<pre style="background:#f0f0f0;padding:10px;font-size:11px;">';
    $output .= '登録済みショートコード一覧:' . PHP_EOL;
    foreach ($registered as $tag) {
        $output .= '  [' . $tag . ']' . PHP_EOL;
    }
    $output .= '</pre>';
    return $output;
});

// ショートコードが正しく出力されているか確認
add_action('shutdown', function(): void {
    if (!is_admin() || !current_user_can('administrator')) {
        return;
    }
    if (isset($_GET['test_shortcode'])) {
        $result = do_shortcode('[my_shortcode id="1"]');
        error_log('[shortcode test] ' . substr(strip_tags($result), 0, 200));
    }
});

# ショートコードを含むコンテンツを持つ投稿を確認
wp post list --post_status=publish --fields=ID,post_title \
    --search="[my_shortcode" 2>/dev/null || \
wp eval "
\$posts = get_posts(['s' => '[my_shortcode', 'posts_per_page' => 5]);
foreach (\$posts as \$p) echo \$p->ID . ': ' . \$p->post_title . PHP_EOL;
"

注意事項

ショートコードのコールバック関数は必ず文字列をreturnしてください。echoではなくreturnが必須です。echoすると出力位置が期待と異なる場所になります
add_shortcode()はinitフックより前（プラグインのロード時）に呼び出せますが、WP_Queryやget_post()などのWordPress関数を使う場合はinitフック以降で処理してください
ブロックエディター（Gutenberg）ではショートコードブロックを使えますが、将来的な互換性のためにカスタムブロックへの移行を検討してください

まとめ

ショートコードのトラブル解決は①wp evalで$shortcode_tagsを確認し登録状態をチェック、②add_shortcode()でコールバックがreturnする文字列を返すよう正しく実装、③テキストウィジェット・カスタムフィールドにはadd_filter('widget_text', 'do_shortcode')で有効化、④ブロックエディターでは「ショートコード」ブロックを使用するかカスタムブロックにrender_callbackを実装、⑤[debug_shortcode]で登録済み一覧を確認してデバッグします。

Post Views: 21