2026年7月5日

Beaver Builderのエラーを解決する方法

プラグイン関連

はじめに

Beaver Builderでページ編集画面を開こうとすると白い画面になって編集できない・公開済みページでモジュールのコンテンツが表示されず空白になる・スマートフォンでの表示レイアウトがビルダーのプレビューと実際の表示で異なる・カスタムモジュールを追加したが使えないといった問題は、プラグインの競合・JavaScriptエラー・キャッシュの残存が原因です。

症状・原因

Beaver Builderの「Launch」ボタンを押してもビルダー画面が開かず通常のページが表示される
編集画面では正しく表示されるがフロントエンドで特定モジュール（画像・動画等）が表示されない
レスポンシブプレビューではモバイル表示が正常だが実際のスマートフォンでは崩れている
add_action('fl_builder_register_module')で追加したカスタムモジュールが選択肢に出ない

解決手順

ステップ1：Beaver Builderの状態を確認する

# Beaver Builderの設定確認
wp eval "
if (defined('FL_BUILDER_VERSION')) {
    echo 'Beaver Builder version: ' . FL_BUILDER_VERSION . PHP_EOL;
}

// BB設定を確認
\$settings = get_option('_fl_builder_settings', []);
echo 'Cache enabled: '  . ((\$settings['cache'] ?? true) ? 'yes' : 'no') . PHP_EOL;
echo 'Module cache: '   . ((\$settings['module_cache'] ?? true) ? 'yes' : 'no') . PHP_EOL;

// BBでビルドされたページを確認
global \$wpdb;
\$bb_pages = \$wpdb->get_var(
    \"SELECT COUNT(*) FROM \$wpdb->postmeta WHERE meta_key = '_fl_builder_enabled' AND meta_value = '1'\"
);
echo 'Pages with BB enabled: ' . \$bb_pages . PHP_EOL;

// キャッシュファイルを確認
\$cache_dir = WP_CONTENT_DIR . '/uploads/bb-plugin/cache/';
if (is_dir(\$cache_dir)) {
    \$files = glob(\$cache_dir . '*.css');
    echo 'CSS cache files: ' . count(\$files) . PHP_EOL;
    \$files = glob(\$cache_dir . '*.js');
    echo 'JS cache files: '  . count(\$files) . PHP_EOL;
    // 古いキャッシュを削除
    foreach (glob(\$cache_dir . '*') as \$file) {
        if (is_file(\$file) && filemtime(\$file) < strtotime('-7 days')) {
            unlink(\$file);
        }
    }
    echo 'Old cache files cleaned' . PHP_EOL;
}
"

ステップ2：ビルダーのキャッシュをクリアする

// functions.php: Beaver Builderキャッシュ管理

// ① 投稿更新時にBBキャッシュをクリア
add_action('save_post', function(int $post_id): void {
    if (!class_exists('FLBuilderModel')) return;
    if (wp_is_post_revision($post_id)) return;

    // BB のキャッシュをクリア
    FLBuilderModel::delete_asset_cache_for_post($post_id);

    error_log(sprintf('[BB] Cache cleared for post #%d', $post_id));
});

// ② テーマ更新時にBBグローバルキャッシュをクリア
add_action('upgrader_process_complete', function(): void {
    if (!class_exists('FLBuilderModel')) return;
    FLBuilderModel::delete_all_asset_cache();
    error_log('[BB] Global cache cleared after theme/plugin update');
});

// ③ 特定ページのBBレイアウトデータを取得
function get_bb_layout_data(int $post_id): array {
    if (!class_exists('FLBuilderModel')) return [];

    $layout_data = FLBuilderModel::get_layout_data('published', $post_id);
    return $layout_data ?: [];
}

// ④ プログラムでBBキャッシュの完全クリア
add_action('admin_init', function(): void {
    if (!isset($_GET['fl_clear_cache']) || !current_user_can('manage_options')) return;

    if (!class_exists('FLBuilderModel')) return;
    FLBuilderModel::delete_all_asset_cache();
    wp_cache_flush();

    wp_redirect(admin_url('?fl_cache_cleared=1'));
    exit;
});

ステップ3：カスタムモジュールを作成する

// functions.php: カスタムBBモジュール登録

// ① カスタムモジュールのクラスを定義
add_action('init', function(): void {
    if (!class_exists('FLBuilderModule')) return;

    // カスタム「CTAボックス」モジュール
    FLBuilder::register_module('MyCtaModule', [
        'general' => [
            'title'    => '一般設定',
            'sections' => [
                'content' => [
                    'title'  => 'コンテンツ',
                    'fields' => [
                        'title' => [
                            'type'    => 'text',
                            'label'   => 'タイトル',
                            'default' => 'CTAタイトルを入力',
                        ],
                        'description' => [
                            'type'  => 'textarea',
                            'label' => '説明文',
                        ],
                        'button_text' => [
                            'type'    => 'text',
                            'label'   => 'ボタンテキスト',
                            'default' => '今すぐ申し込む',
                        ],
                        'button_url' => [
                            'type'  => 'link',
                            'label' => 'ボタンURL',
                        ],
                        'bg_color' => [
                            'type'    => 'color',
                            'label'   => '背景色',
                            'default' => '2271b1',
                        ],
                    ],
                ],
            ],
        ],
    ]);
});

// カスタムモジュールのクラス（別ファイルに分けることを推奨）
class MyCtaModule extends FLBuilderModule {
    public function __construct() {
        parent::__construct([
            'name'            => 'CTAボックス',
            'description'     => 'カスタムCTAボックスモジュール',
            'category'        => 'カスタムモジュール',
            'dir'             => get_template_directory() . '/bb-modules/cta/',
            'url'             => get_template_directory_uri() . '/bb-modules/cta/',
            'editor_export'   => true,
            'enabled'         => true,
            'partial_refresh' => true,
        ]);
    }
}

ステップ4：モジュールのレンダリングをカスタマイズする

// functions.php: BBモジュールレンダリング

// ① モジュール出力をフィルタリング
add_filter('fl_builder_render_module_html', function(string $out, string $type, object $settings): string {
    // 画像モジュールにlazy loadingを追加
    if ($type === 'photo') {
        $out = str_replace('<img ', '<img loading="lazy" ', $out);
    }
    return $out;
}, 10, 3);

// ② BBレイアウトレンダリング前後にフック
add_action('fl_builder_before_render_ajax_layout', function(): void {
    // AJAXレンダリング前にキャッシュを無効化
    define('DONOTCACHEPAGE', true);
});

// ③ BBのJSエラーをデバッグ
add_action('wp_footer', function(): void {
    if (!FLBuilderModel::is_builder_active()) return;
    ?>
    <script>
    window.addEventListener('error', function(e) {
        if (e.filename && e.filename.includes('bb-plugin')) {
            console.error('[BB Error]', e.message, 'at', e.filename + ':' + e.lineno);
        }
    });
    </script>
    <?php
});

ステップ5：レスポンシブ表示の問題を修正する

# BBのレスポンシブ設定確認
wp eval "
// BBのグローバル設定を確認
\$global_settings = FLBuilderModel::get_global_settings();

echo 'Responsive enabled: '      . (\$global_settings->responsive_enabled ? 'yes' : 'no') . PHP_EOL;
echo 'Medium breakpoint: '       . \$global_settings->medium_breakpoint . 'px' . PHP_EOL;
echo 'Responsive breakpoint: '   . \$global_settings->responsive_breakpoint . 'px' . PHP_EOL;
echo 'Auto spacing: '            . (\$global_settings->auto_spacing ? 'yes' : 'no') . PHP_EOL;

// BBキャッシュ情報
\$cache_dir = WP_CONTENT_DIR . '/uploads/bb-plugin/cache/';
\$total_size = 0;
foreach (glob(\$cache_dir . '*') as \$file) {
    if (is_file(\$file)) \$total_size += filesize(\$file);
}
echo 'Total cache size: ' . size_format(\$total_size) . PHP_EOL;
"

注意事項

Beaver Builderの編集画面が開かない場合は、まず他のプラグインをすべて無効化してから試してください。特にセキュリティプラグイン（Wordfence等）がBBのAJAXリクエストをブロックすることがあります
BBのキャッシュファイルはwp-content/uploads/bb-plugin/cache/に保存されます。FTPで直接このフォルダの内容を削除することでキャッシュをクリアできます。管理画面が開けない障害時に有効です
カスタムモジュールを追加する場合はinitフックではなくfl_builder_register_moduleフックを使用することを推奨します。initフックではFLBuilderModuleクラスがまだ読み込まれていない場合があります

まとめ

Beaver Builder修復は①_fl_builder_enabledメタでBB使用ページ数・キャッシュファイル数を確認・古いキャッシュを削除、②save_postフックでFLBuilderModel::delete_asset_cache_for_post()・upgrader_process_completeフックでグローバルキャッシュクリア、③FLBuilder::register_module()でカスタムモジュールを登録・FLBuilderModule継承クラスでdir/url/nameを設定、④fl_builder_render_module_htmlフィルターで画像にlazy loading追加・wp_footerフックでBBのJSエラーをデバッグ、⑤FLBuilderModel::get_global_settings()でブレークポイント・レスポンシブ設定を確認する手順で解決します。

Post Views: 4