WordPressのテーマカスタマイザーが動作しない問題を解決する方法

はじめに

WordPressの「外観」→「カスタマイズ」を開くとプレビューエリアが真っ白になる・カスタマイザーで色やフォントを変更して「公開」ボタンを押しても変更がフロントエンドに反映されない・get_theme_mod()が常に空の値を返す・カスタマイザーのパネルやセクションが意図した順番で表示されないといった問題は、JavaScriptエラー・REST APIの無効化・テーマのカスタマイザー実装の不備・オプションキャッシュの問題が原因です。

症状・原因

• カスタマイザーのプレビューフレームがJavaScriptエラーでレンダリングに失敗している
• customize_registerフックの優先度が遅く親テーマのデフォルト設定が子テーマを上書きしている
• get_theme_mod()で取得しているキーとadd_setting()で登録したIDが一致していない
• カスタマイザーの変更がtheme_mods_{theme_slug}オプションに正しく保存されていない

解決手順

ステップ1：カスタマイザーの状態を診断する

# テーマモッドの保存状態を確認
wp eval "
\$theme = get_stylesheet();
\$mods  = get_theme_mods();
echo 'Theme: ' . \$theme . PHP_EOL;
echo 'Stored mods: ' . PHP_EOL;
foreach (\$mods as \$key => \$value) {
    echo '  ' . \$key . ': ' . substr(print_r(\$value, true), 0, 60) . PHP_EOL;
}
"

# カスタマイザー設定の確認
wp eval "
global \$wp_customize;
if (!isset(\$wp_customize)) {
    require_once ABSPATH . WPINC . '/class-wp-customize-manager.php';
    \$wp_customize = new WP_Customize_Manager();
    do_action('customize_register', \$wp_customize);
}
\$settings = \$wp_customize->settings();
echo 'Registered settings: ' . count(\$settings) . PHP_EOL;
foreach (array_slice(\$settings, 0, 10) as \$id => \$setting) {
    echo '  ' . \$id . ' (type: ' . \$setting->type . ')' . PHP_EOL;
}
"

ステップ2：カスタマイザーを正しく実装する

// functions.php: カスタマイザーの正しい実装

add_action('customize_register', function(WP_Customize_Manager $wp_customize): void {
    // パネルを追加
    $wp_customize->add_panel('my_theme_panel', [
        'title'    => 'テーマ設定',
        'priority' => 30,
    ]);

    // セクションを追加
    $wp_customize->add_section('my_colors_section', [
        'title'    => 'カラー設定',
        'panel'    => 'my_theme_panel',
        'priority' => 10,
    ]);

    // 設定を追加（IDはget_theme_mod()で使うキーと一致させる）
    $wp_customize->add_setting('primary_color', [
        'default'           => '#0073aa',
        'type'              => 'theme_mod',        // theme_mod または option
        'transport'         => 'postMessage',      // refresh または postMessage
        'sanitize_callback' => 'sanitize_hex_color',
    ]);

    // コントロールを追加
    $wp_customize->add_control(new WP_Customize_Color_Control(
        $wp_customize,
        'primary_color',
        [
            'label'    => 'メインカラー',
            'section'  => 'my_colors_section',
            'settings' => 'primary_color',
        ]
    ));
});

ステップ3：カスタマイザーのliveプレビューをJSで実装する

// functions.php: postMessage transportのJS実装

add_action('customize_preview_init', function(): void {
    wp_enqueue_script(
        'my-theme-customizer',
        get_template_directory_uri() . '/js/customizer.js',
        ['customize-preview', 'jquery'],
        filemtime(get_template_directory() . '/js/customizer.js'),
        true
    );
});

// js/customizer.js: リアルタイムプレビューの実装
(function($) {
    // メインカラーのリアルタイム反映
    wp.customize('primary_color', function(value) {
        value.bind(function(newVal) {
            // CSSカスタムプロパティを更新
            document.documentElement.style.setProperty('--color-primary', newVal);
            // または特定要素のスタイルを直接変更
            $('a, .btn-primary').css('color', newVal);
        });
    });

    // サイトタイトルのリアルタイム反映
    wp.customize('blogname', function(value) {
        value.bind(function(newVal) {
            $('.site-title a').text(newVal);
        });
    });
})(jQuery);

ステップ4：get_theme_mod()でカスタマイザー値を出力する

// テンプレートファイル: カスタマイザー値の正しい取得と出力

// functions.php: CSSカスタムプロパティとしてカスタマイザー値を出力
add_action('wp_head', function(): void {
    $primary_color = sanitize_hex_color(get_theme_mod('primary_color', '#0073aa'));
    $font_size     = absint(get_theme_mod('base_font_size', 16));
    ?>
    <style id="my-theme-custom-css">
        :root {
            --color-primary: <?php echo esc_attr($primary_color); ?>;
            --font-size-base: <?php echo esc_attr($font_size); ?>px;
        }
    </style>
    <?php
});

// テーマモッドを削除して初期値にリセット
// remove_theme_mod('primary_color');
// または全モッドをリセット
// remove_theme_mods();

# テーマモッドを直接設定
wp eval "
set_theme_mod('primary_color', '#d63638');
echo 'primary_color set to: ' . get_theme_mod('primary_color') . PHP_EOL;
"

# テーマモッドをリセット
wp eval "
remove_theme_mod('primary_color');
echo 'primary_color removed. Default: ' . get_theme_mod('primary_color', '#0073aa') . PHP_EOL;
"

ステップ5：カスタマイザーの保存エラーを修正する

// functions.php: カスタマイザー保存時のカスタム処理

// カスタマイザー保存後のフック
add_action('customize_save_after', function(WP_Customize_Manager $manager): void {
    // カスタマイザー保存後にCSS静的ファイルを再生成
    $primary_color = $manager->get_setting('primary_color')->value();
    $css = ":root { --color-primary: {$primary_color}; }";
    file_put_contents(
        get_template_directory() . '/css/custom-variables.css',
        sanitize_hex_color($primary_color) ? $css : ''
    );
    // キャッシュをクリア
    wp_cache_delete('my_theme_custom_css', 'my_theme');
});

// カスタマイザーの保存権限をカスタマイズ
add_filter('customize_changeset_save_data', function(array $data, array $context): array {
    // 追加のバリデーションロジック
    return $data;
}, 10, 2);

注意事項

• transportをpostMessageに設定した場合は必ずJavaScriptでリアルタイムプレビューを実装してください。JSなしでpostMessageにするとカスタマイザーで変更してもプレビューが更新されません
• get_theme_mod()のキーはadd_setting()で登録したIDと完全に一致する必要があります。大文字小文字・アンダースコアの有無を必ず確認してください
• 子テーマで親テーマのカスタマイザー設定を変更する場合はcustomize_registerフックの優先度を20以上に設定して親テーマの登録後に実行されるようにしてください

まとめ

WordPressテーマカスタマイザー不動作の解決は①get_theme_mods()で保存済みモッドを確認・WP_Customize_Managerを初期化して登録済み設定数を確認・ブラウザのコンソールでJSエラーを特定、②customize_registerフックでadd_panel→add_section→add_setting→add_controlの順に登録・type=theme_modとsanitize_callbackを必ず設定・transport=postMessageでリアルタイムプレビューを有効化、③customize_preview_initでcustomizer.jsを登録・wp.customize(キー, fn)でJS側のリアルタイム変更を実装、④get_theme_mod(キー, デフォルト値)でテンプレート側で取得・wp_headフックでCSSカスタムプロパティとして出力・set_theme_mod()でWP-CLIからデバッグ、⑤customize_save_afterフックで保存後にCSS再生成・wp_cache_deleteでキャッシュクリア・子テーマのフック優先度を20以上に設定の手順で解決します。