WooPaymentsでカード追加ページが真っ白になる原因と解消手順

WooPaymentsでカード追加ページが真っ白になる原因と解消手順

WooCommerceでWooPaymentsを使っているサイトで、購入時のカード保存は正常に動くのにマイアカウントのカード追加ページだけが真っ白になる場合、多くはJavaScriptエラーかプラグインによるテンプレート競合が原因だ。開発者ツールでエラーの実体を特定し、プラグインとテーマの切り分けを順に行うと短時間で解消できる。

なぜカード追加ページだけが真っ白になるのか

WooPaymentsのカード入力フォームは、チェックアウト画面でもマイアカウント内でもJavaScriptで動的に描画される。特にカード追加ページでは、WooPaymentsが提供するStripe Elementsという入力部品を読み込んでフォームを生成する仕組みだ。

このとき、他のプラグインが読み込むスクリプトと衝突したり、テーマがマイアカウントのテンプレートを上書きしてフォームの置き場所が消えたりすると、ページが真っ白に見える。PHPの致命的エラーが起きている場合も同様の症状になる。

保存済みカードの一覧表示は正常なのにカード追加だけが空になるのは、表示に異なる読み込み経路が使われるためだ。一覧はすでにデータベースへ保存された情報をPHPだけで描画できるが、カード追加フォームはJavaScriptの実行が必須になる。だからこそ、スクリプトエラーが症状としてそのページだけに出やすい。

また、WooPaymentsのアップデート時にファイルの一部が欠けた場合もフォームが表示されない。エラーがどこにも出ないまま空白だけになるケースでは、プラグイン本体の再インストールも選択肢に入る。

ブラウザの開発者ツールでエラーを特定する手順

まず最初に、ブラウザの開発者ツールを使って実際に何が止まっているのかを確認する。エラーが特定できれば、その後の切り分けが大幅に短くなる。

このデモは、エラー特定までの基本フローを示している。コンソールとネットワークの両方を確認すると原因ファイルが見つかりやすい。

コンソールでJavaScriptエラーを確認する

カード追加ページを開いた状態でF12キーを押し、「コンソール」タブを開く。赤い文字で表示されるエラーが1件以上あれば、その内容を控えておく。英語表示の場合は「Uncaught TypeError」や「Failed to load resource」のような記述が手がかりになる。

エラーの右側に表示されるファイル名も重要だ。どのプラグインのスクリプトが失敗しているかが分かれば、無効化の対象を特定できる。たとえば `woocommerce.js` や `stripe.js` が読み込めていなければ、キャッシュやプラグイン本体の問題を疑う。

ネットワークタブで読み込み失敗を確認する

同じく開発者ツールの「ネットワーク」タブを開き、ページを再読み込みする。ステータスが「404」や「500」になっているファイルがないかを確認する。404はファイルが存在しない、500はサーバー処理の失敗を意味する。

とくにカードフォームの描画に必要なJavaScriptファイルが404になっていると、ページが白いまま何も表示されない。この場合はWooPaymentsのファイルが不完全な可能性が高い。

プラグインとテーマの競合を切り分ける手順

開発者ツールで原因が特定できない場合は、定番の切り分け作業を順に行う。目的は、どのプラグインまたはテーマがカード追加ページの表示を妨げているかを絞り込むことだ。

このデモは、プラグイン競合の切り分け前後で何が変わるかを示している。競合元を特定しなければ恒久的な解決にはならない。

全プラグインを無効化してWooCommerce系だけ有効化する

管理画面の「プラグイン」へ移動し、(WooCommerceとWooPayments以外の)すべてのプラグインを無効化する。この状態でカード追加ページを開いてフォームが表示されるか確認する。

フォームが表示された場合は、無効化したプラグインをひとつずつ有効化して、どのプラグインを有効にした時点で再発するかを確認する。マイアカウントの表示をカスタマイズするプラグインや、管理画面用のスクリプトを全ページに読み込むプラグインが原因になりやすい。

この作業で一時的にサイト機能が変わるため、アクセスの少ない時間帯に行うか、ステージング環境があればそちらで再現させる。WooCommerceとWooPaymentsは必ず有効のままにして検証する。

標準テーマに切り替えてテーマの影響を除外する

プラグインをすべて無効化しても症状が続く場合は、テーマが原因の可能性がある。管理画面の「外観」→「テーマ」で、Twenty Twenty-FourなどのWordPress標準テーマへ一時的に切り替える。

標準テーマでカード追加フォームが表示されるなら、元のテーマがマイアカウントのテンプレートを上書きしていることになる。テーマに含まれる `woocommerce` フォルダの `myaccount` 関連ファイルが、カード追加ページの表示を妨げているケースが多い。

テーマを切り替えるとウィジェットやカスタマイズ設定が変わることがあるため、検証後は必ず元のテーマへ戻す。できればステージング環境での検証を推奨する。

WooPaymentsの設定とパーマリンクを再確認する

切り分けを行っても原因が見つからない場合、WooCommerceの設定とパーマリンクを再確認する。設定が正しくても保存し直すだけで直るケースがある。

カード追加エンドポイントの設定を保存し直す

管理画面の「WooCommerce」→「設定」→「詳細設定」タブを開き、「アカウントエンドポイント」欄を確認する。カード追加の項目が正しく入力されていることを確認し、入力内容そのものに変更がなくても一度「変更を保存」を押す。

パーマリンクの内部マップがずれていると、ページ自体は存在してもWooCommerceがエンドポイントを認識できないことがある。保存し直すだけでマップが再構築されるため、手軽に試せる。

保存済みカード決済の設定を確認する

「WooCommerce」→「設定」→「決済」タブでWooPaymentsを開き、「カード決済」が有効であることと「保存済みカードによる支払いを有効にする」にチェックが入っていることを確認する。購入時のカード保存は正常でも、この設定が外れるとマイアカウントからの追加だけが動作しないことがある。

パーマリンクを更新してエンドポイントを再マップする

管理画面の「設定」→「パーマリンク」へ移動し、設定を変更せずそのまま「変更を保存」を押す。これでリライトルールが再生成され、マイアカウントの各エンドポイントが正しく認識されるようになる。

パーマリンク更新後は必ずキャッシュプラグインのキャッシュを全削除する。キャッシュが残っていると、古い状態のページが配信されて症状が続いているように見える。

再発を防ぐための更新前チェックとログ確認

根本解決できたら、次回のアップデートで同じ問題が起きないように更新前チェックの習慣をつけておく。WooPaymentsは更新頻度が高いプラグインのため、更新後に特定のページだけが壊れるリスクは常にある。

WooCommerceのログでPHPエラーを確認する

管理画面の「WooCommerce」→「ステータス」→「ログ」タブを開き、直近のエラーログに「fatal-errors」のようなファイルがないかを確認する。PHPの致命的エラーが記録されていれば、その内容から原因ファイルを特定できる。

ログが存在しない場合は、WooPaymentsの「ログ」タブから決済関連の動作記録を確認する。カード追加フォームの読み込みに失敗した形跡がないかを探る。

WooPaymentsのファイルを再アップロードする

アップデート時にファイルの一部が欠けた疑いがある場合は、管理画面からプラグインを削除して再インストールする。その際、決済データはサーバー側に保存されているため、プラグインの削除で売上情報や顧客情報が消えることはない。

FTP接続でWooPaymentsのフォルダだけを最新版のファイルで上書きする方法もある。管理画面に入れる状態なら「プラグイン」→「プラグインの新規追加」からWooPaymentsを検索して入れ直す方が確実だ。

マイアカウント系ページをキャッシュ対象から除外する

キャッシュプラグインの設定で、マイアカウント関連のURLをキャッシュ対象から除外しておく。具体的には `/my-account/` で始まるパスを除外リストへ追加する。これにより、カードフォームや認証情報が古いキャッシュで表示される問題を防げる。

よくある質問

カード追加ページだけが真っ白になるのはなぜ？

そのページだけテンプレートやJavaScriptが干渉されている可能性が高い。WooPaymentsのカード入力フォームはJavaScriptで描画されるため、他のプラグインのスクリプトが衝突するとフォームが生成されず真っ白に見える。

開発者ツールにエラーが表示されない場合は？

コンソールにエラーが出ない場合、PHPの処理途中で止まっている可能性を疑う。wp-config.phpでデバッグを有効にしてエラーを可視化するか、WooCommerceのログを確認する。あわせてテーマのマイアカウント用テンプレートが正しいかも調べる。

WooPaymentsのバージョンを一つ前へ戻すと直る？

互換性が問題の場合は直ることがある。バージョン固定のダウングレードは応急処置として有効だが、セキュリティ更新を含む場合は推奨しない。まず競合の特定を優先し、どうしても手がかりがない場合に実施する。

キャッシュプラグインが原因になることはある？

ある。特にマイアカウント系のページをキャッシュしてしまう設定だと、カードフォームの読み込みだけが古い状態で配信されることがある。キャッシュ対象からマイアカウントを除外する設定も併せて確認する。

マイアカウントの表示をカスタマイズするプラグインは原因になりやすい？

なりやすい。カード追加ページのテンプレートやフックを書き換えるタイプのプラグインは、WooPaymentsのフォーム表示に直接影響する。無効化して症状が消えるかどうかを最初の切り分けで確認する。

この記事のポイント

• 開発者ツールのコンソールでJavaScriptエラーを特定する
• 全プラグインを無効化してWooCommerce系だけ有効化して切り分ける
• 標準テーマに切り替えてテーマ競合を除外する
• パーマリンクとエンドポイント設定を保存し直す
• WooPaymentsを再インストールしてファイルの健全性を回復する
• マイアカウント系ページをキャッシュ対象から除外する

佐々木 太陽

・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている