はじめに
記事に エラー: コンタクトフォームが見つかりません。
症状・原因
ショートコードが動作しない主な原因：
- プラグインが無効：ショートコードを登録しているプラグインが無効化されている
- テーマのフィルター不足：
the_contentフィルターが正しくかかっていない - ウィジェットでの制限：デフォルトではウィジェットにショートコードが使えない
- ブロックエディターの問題：クラシックブロックとショートコードブロックの混在
- 登録前に呼び出し：プラグインのロード前にショートコードを使おうとしている
解決手順
ステップ1：ショートコードが登録されているか確認する
// ショートコードが登録済みかデバッグ確認
add_action('wp_footer', function() {
if (current_user_can('administrator')) {
global $shortcode_tags;
echo '<!-- Registered shortcodes: ';
echo implode(', ', array_keys($shortcode_tags));
echo ' -->';
}
});WP-CLIで確認：
# 全ショートコードを確認
wp eval 'global $shortcode_tags; print_r(array_keys($shortcode_tags));'ステップ2：カスタムテンプレートでdo_shortcodeを使う
// page.php や single.php — ショートコードを手動で処理
<?php
$content = get_the_content();
echo apply_filters('the_content', $content);
// または
echo do_shortcode($content);
?>the_content()ではなくget_the_content()を直接echoしている場合はapply_filtersが必要です。
ステップ3：ウィジェットでショートコードを有効化する
// functions.php — テキストウィジェットでショートコードを有効化
add_filter('widget_text', 'do_shortcode');
add_filter('widget_text_content', 'do_shortcode');
// カスタムHTMLウィジェットでも有効化
add_filter('widget_custom_html_content', 'do_shortcode');ステップ4：ブロックエディターでショートコードを使う
ブロックエディターでは「ショートコード」ブロックを使います。
1. 「+」ブロック追加 → 「ショートコード」を検索
2. ショートコードブロックにショートコードを入力
3. プレビューで正しく表示されるか確認
または「クラシック」ブロックに切り替えてビジュアルエディターに書く方法もあります。
ステップ5：カスタムショートコードを正しく実装する
// functions.php — ショートコードの正しい実装
add_shortcode('my_button', function($atts, $content = null) {
// デフォルト属性を設定
$atts = shortcode_atts([
'color' => 'blue',
'url' => '#',
'size' => 'medium',
], $atts, 'my_button');
$color = esc_attr($atts['color']);
$url = esc_url($atts['url']);
$label = $content ? esc_html($content) : 'クリック';
// 出力はreturnで返す（echoしない）
return sprintf(
'<a href="%s" class="btn btn-%s btn-%s">%s</a>',
$url, $color, esc_attr($atts['size']), $label
);
});
// 使い方: [my_button color="red" url="/contact"]お問い合わせ[/my_button]重要：ショートコードのコールバック内ではechoせず必ずreturnで返してください。echoすると出力位置が意図しない場所になります。
ステップ6：プラグインのショートコードが動かない場合
# プラグインを一つずつ有効化して競合を確認
wp plugin deactivate --all
wp plugin activate contact-form-7
# ショートコードが動くか確認
# 問題のプラグインを特定したら
wp plugin activate all-other-pluginsステップ7：PHPのショートコードデバッグ
// 独自ショートコードのデバッグ（WP_DEBUGがtrueの環境で）
add_shortcode('debug_test', function($atts) {
ob_start();
var_dump($atts);
return ob_get_clean();
});
// [debug_test key="value"] で属性が正しく渡るか確認注意事項
- ショートコードのコールバックは必ず
returnを使い、echoは使わないでください。 - セキュリティのため、ショートコードで出力するHTMLは
esc_html()・esc_url()・esc_attr()でエスケープしてください。 - ショートコードは
add_shortcode()を呼ぶプラグインが有効でないと動きません。
まとめ
ショートコードが動かない場合は、プラグインが有効かどうか、テーマがthe_contentフィルターを適用しているかどうかを最初に確認します。ウィジェットではadd_filter('widget_text', 'do_shortcode')を追加することで有効化できます。関連記事：カスタムフィールドが保存できない場合、ブロックエディターの使い方