Rank MathでWooCommerceモジュールが開けない時の原因と対処法
Rank MathのWooCommerceモジュールがグレーアウトして切り替えられない場合、原因はプラグインのデータベースマイグレーションが完了していないことにある。管理画面に表示されるデータベースバージョンが初期値の1のままなら、まずキャッシュの全削除とメモリ上限の確認を行い、その上で不要オプションを削除して再マイグレーションを発生させる。
なぜWooCommerceモジュールだけがロックされるのか
Rank Mathは各機能をモジュール単位で管理している。WooCommerceモジュールもその一つで、商品の構造化データや詳細設定をまとめて扱う。ところがこのモジュールは、プラグインのデータベーススキーマが特定のバージョン以上になった時だけ有効化できる仕組みだ。
管理画面のステータス情報で「database_version」がいつまでも初期値の1のままだと、WooCommerceモジュールを含む一部の機能が「未導入」と判断されたままになる。トグルにマウスを重ねると「Please activate WooCommerce to use this module」という趣旨のツールチップが表示されるが、WooCommerce本体が有効化されていてもこのエラーは出る。
つまり、WooCommerceの有効・無効が問題なのではなく、Rank Math側のデータベース情報が古いまま更新されていないことが本質のトラブルだ。
database_versionが1のまま進まない主な原因
Rank Mathのインストール時やセットアップウィザード実行時、プラグイン内部でデータベーステーブルの作成とデータ移行が走る。この処理が最後まで到達しないと、バージョン情報が初期値の1から更新されない。具体的な原因は大きく三つに分けられる。
キャッシュプラグインが古いオプションを保持している
WP Super Cacheに代表されるキャッシュプラグインは、ページ表示を高速化するために一時データを保持する。まれにデータベースのオプション情報まで古い状態のまま配信することがあり、これが原因でRank Mathのバージョン情報が更新されないケースがある。
PHPメモリ上限が低くマイグレーションが途中で止まる
WooCommerceサイトは通常のWordPressサイトより管理画面のメモリ消費が大きい。Elementorや高機能テーマも動いている場合、PHPのメモリ上限を超えてRank Mathのデータベース処理が途中で終了してしまうことがある。具体的にはwp-config.phpで定義されたWP_MEMORY_LIMITが40M程度だと、重い環境では不足しやすい。
rank_math_db_versionオプションが破損している
WordPressのオプションテーブル（wp_options）には、Rank Mathが利用する複数のオプションが保存されている。このうち「rank_math_db_version」という値が破損したり、不正な状態で固定されたりすると、セットアップウィザードを再実行しても値が更新されない。
モジュールロックを解除する具体的な手順
以下の手順は、データベースバージョンが初期値から更新されない場合に有効だ。順に実行することで、Rank Mathのマイグレーションが正常に走り、WooCommerceモジュールのロックが外れる。
このデモは、Rank Mathのデータベースバージョンを固定している原因を取り除き、マイグレーションを再実行させる流れを示している。
キャッシュを完全に無害化する
管理画面のプラグインページでWP Super Cacheを一時的に無効化する。次に「設定」→「WP Super Cache」からキャッシュの削除を実行し、サーバー上のwp-contentディレクトリにあるcacheディレクトリ内のファイルも手動で削除しておく。
共有サーバーで管理画面から操作できない場合は、FTPソフトでwp-content/cacheに入り、中身を空にする。キャッシュを消した後は、ブラウザのキャッシュも混ざらないようシークレットウィンドウで確認すると確実だ。
WP_MEMORY_LIMITを引き上げる
FTPまたはサーバーのファイルマネージャーでwp-config.phpを開き、WP_MEMORY_LIMITの定義を探す。設定されていなければ「/* That’s all, stop editing! */」の直前に以下の行を追加する。
define( 'WP_MEMORY_LIMIT', '128M' );すでに40Mなど低い値が指定されている場合は、128Mまたは256Mに書き換える。変更後にWordPress管理画面の「ツール」→「サイトヘルス」からPHPのメモリ上限が更新されているか確認できる。
rank_math_db_versionオプションを直接削除する
サーバーのphpMyAdminにアクセスし、該当サイトのデータベースを選択する。wp_optionsテーブルを開き、option_nameが「rank_math_db_version」の行を探して削除する。
SQLを直接実行できる環境なら、次のようにしても同じ結果になる。
DELETE FROM wp_options WHERE option_name = 'rank_math_db_version';テーブルの接頭辞がwp_以外の場合は、実際の接頭辞に置き換える。削除後、Rank Mathの管理画面を開くとマイグレーションが自動的に再実行され、正常ならデータベースバージョンが初期値より大きい値に更新される。
rank_math_modulesオプションも削除する
rank_math_db_versionを削除してもWooCommerceモジュールがロックされたままの場合、rank_math_modulesというオプションも同様に削除する。この値には有効化済みモジュールのリストが保存されており、破損しているとモジュールの出し分けが正常に機能しない。
DELETE FROM wp_options WHERE option_name IN ('rank_math_db_version', 'rank_math_modules');この二つを削除した後、Rank Mathのセットアップウィザードを「詳細モード」で最後まで実行する。WooCommerceモジュールのトグルが青くなり、切り替え可能になっていれば成功だ。
それでも直らない場合の最終確認
データベースユーザーにテーブル作成権限があるか
Rank Mathのマイグレーションは、専用のテーブル（rank_math_analytics_objectsなど）を作成してデータを保存する。データベースユーザーに「CREATE TABLE」権限がないと、処理が裏側で失敗し続ける。レンタルサーバーの管理画面からデータベースユーザーの権限を確認し、不足していれば付与する。
重いプラグインを停止してからもう一度
ElementorやSlider Revolutionなど、管理画面の動作を重くするプラグインがマイグレーションを妨げている可能性がある。Health Check & Troubleshootingプラグインのトラブルシューティングモードを使い、Rank MathとWooCommerceだけを有効化した状態で手順をもう一度試す。
Rank Mathのデータベースツールでテーブルを作り直す
Rank Mathの管理画面から「ステータスとツール」→「データベースツール」を開く。「テーブルを作り直す」や「データベースを修復」といったボタンが用意されているので、順に実行してテーブルの再作成とデータの再構築を行う。
その後、もう一度セットアップウィザードを完了させ、データベースバージョンの値が更新されるかを確認する。それでも値が1のままなら、プラグインのアップデート待ちか、サーバー環境固有の制約が残っている可能性が高い。
よくある質問
トグルをクリックしても何も反応しないのはなぜ？
WooCommerceモジュールがロックされていると、トグル自体がグレーアウトした状態になる。クリックしても切り替わらず、ツールチップだけが表示される。これは操作ミスではなく、Rank Math内部でモジュールが使えない状態として認識されているためだ。
WooCommerce本体が壊れている可能性はある？
WooCommerceがプラグインページで有効化されており、商品管理やカートなど通常機能が動いているなら本体は正常だ。今回の問題はRank Math側のデータベース情報が古いことが原因なので、WooCommerceを再インストールしても解決しない。
Rank Mathを削除して入れ直しても直らないのはなぜ？
プラグインを削除しても、wp_optionsテーブルに保存されたオプションは残る。再インストール時に古いオプションを読み込んでしまい、同じ状態が再現される。必ずデータベースからrank_math_db_versionを削除してから再インストールする必要がある。
キャッシュプラグインは原因になりうる？
WP Super Cacheなどのキャッシュプラグインはページキャッシュが主体だが、環境によってはデータベースの一時情報も保持することがある。Rank Mathのバージョン情報が更新されない状態が続くなら、キャッシュプラグインを停止して切り分けるのが有効だ。
セットアップウィザードは毎回完了しているのに直らない
ウィザード自体は設定画面を進めるだけで、データベースのマイグレーションは別プロセスで走る。マイグレーションが裏側で失敗していると、ウィザード完了後もdatabase_versionが1のままになる。オプション削除とメモリ上限の引き上げを先に行うことが重要だ。
この記事のポイント
- WooCommerceモジュールのロックはRank Mathのデータベースバージョンが原因
- database_versionが1のままならマイグレーションが未完了
- キャッシュ削除とWP_MEMORY_LIMITの引き上げを先に行う
- rank_math_db_versionとrank_math_modulesオプションを直接削除して再実行
- テーブル作成権限の確認と重いプラグインの停止も有効
・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている
WPLP Cookie Consent脆弱性を狙った攻撃からWordPressを守る3つの対策
Cookie同意プラグイン「WPLP Cookie Consent（スラッグ gdpr-cookie-consent）」のバージョン4.4.1以前には、未認証の攻撃者に任意のファイルをアップロードされる脆弱性がある。サイトを守るには、プラグインを4.4.2以上へ更新し、アップロードディレクトリ内でのPHP実行をサーバー側で拒否し、不正な管理者アカウントが作られていないか確認することが最優先だ。
なぜWPLP Cookie Consent 4.4.1が危険なのか
この脆弱性は、プラグインのREST APIエンドポイントに認可の不備があることから発生する。攻撃者は誰でもアクセスできる2つのエンドポイントを悪用し、WordPressのオプション設定を書き換えたうえで、任意のファイルをサーバーに保存できる。特に問題なのが、保存先が通常のアップロードフォルダ（wp-content/uploads）であり、ファイル名や拡張子の検証がまったく行われていなかった点だ。
つまり攻撃者は「画像ファイルに見せかけたPHPプログラム」をサイトに置くだけで、その後の実行に成功すれば管理者権限を奪取できる。バージョン4.4.1は攻撃が確認された時点で最新版だったため、更新を怠っていたサイトだけでなく、常に最新にしていたサイトも危険にさらされた。修正版の4.4.2が公開されてからは、この経路は塞がれているが、攻撃キャンペーンがすでに自動化されて動いている以上、更新前のサイトは今も標的になる。
攻撃の流れと侵入の仕組み
実際に確認された攻撃は、わずか20秒足らずで4段階のプロセスが自動実行される。最初にユーザー一覧を取得して管理者のユーザー名を特定し、次にプラグイン固有のオプションを毒して鍵をすり替え、最後にその鍵を使ってファイルを書き込む。下の図はその一連の流れを表している。
この攻撃チェーンのうち、最初の3段階は特定のプラグインがなければ成立しない。一方で、最後のPHP実行だけはサーバー側の設定次第でどのサイトでも防げる。ここが多層防御の要になる。
まず行う3つの緊急対応
サイトがこの脆弱性の影響を受けるかどうかに関係なく、次の3つを優先して実行する。順番はプラグインの更新、サーバー設定の確認、不正アカウントの確認が推奨される。
プラグインを4.4.2以上へ更新する
WPLP Cookie Consent（gdpr-cookie-consent）を使っている場合、まず管理画面の「プラグイン」から更新が来ていないか確認する。更新が見つからない場合は、WordPress.orgのプラグインページから最新版を手動でダウンロードし、既存のプラグインを上書きする。バージョン4.4.2では、脆弱性の原因だったアップロード用エンドポイントが削除され、残ったREST APIにもHMAC-SHA256署名によるリクエスト検証が追加されている。
更新後は、キャッシュ系プラグインを使っている場合はキャッシュを削除しておく。古いRESTエンドポイントの応答がキャッシュに残っていると、攻撃者からまだ有効に見えることがあるためだ。
アップロードディレクトリ内でのPHP実行を拒否する
今回の攻撃では、脆弱なプラグインによって「wp-content/uploads」ディレクトリにPHPファイルが書き込まれた。しかし、そのディレクトリ内でのPHP実行がサーバー側で拒否されていたため、攻撃は最終段階で失敗している。この設定は多くのレンタルサーバーで最初から有効になっているが、そうでない環境もある。
Apacheサーバーの場合、wp-content/uploads ディレクトリに以下の内容の .htaccess ファイルを置くことで、PHPファイルの実行を拒否できる。
<FilesMatch "\.(php|php5|phtml)$">
Require all denied
</FilesMatch>Nginxの場合は、サーバー設定で該当ディレクトリに対するPHPの処理を除外する。レンタルサーバーを利用しているなら、管理パネルに「PHP実行の無効化」や「セキュリティ設定」が用意されているか確認する。設定を変更できない場合は、サーバー会社に問い合わせて、アップロードディレクトリ内のPHP実行がブロックされているか確認するのが確実だ。
上の対比のように、ファイルが置かれても実行できなければウェブシェルとして機能しない。プラグインの更新とあわせて、このサーバー側の防御を必ず確認する。
不正な管理者アカウントを探す
今回確認されたマルウェアは、実行に成功すると管理者アカウントを自動生成する。しかも、登録日時を既存ユーザーの日時に合わせて改ざんするため、「新しく作られたユーザー」を探すだけでは見つからない。次の3つの兆候を手がかりに、phpMyAdminやWP-CLIで WordPress の wp_users テーブルを確認する。
- ユーザー名が「サイトのドメイン名＋ランダム3文字」になっている
- 表示名が「Lucas Hayes」になっている
- メールアドレスのドメインが ifuqpatr.com になっている
心当たりのない管理者アカウントを見つけたら、そのユーザーを削除し、全ユーザーのパスワードをリセットする。また、登録日時が既存ユーザーと完全に一致するアカウントがないかもあわせて確認する。
侵害を検知する具体的な手順
すでに攻撃を受けた形跡がないかは、ログとファイルの両面から確認する。攻撃が失敗していても、ファイルの残骸や不審なアクセスが残っていることが多い。
サーバーのアクセスログを精査する
攻撃者は決まったエンドポイントに順番にアクセスする。アクセスログで次のパターンを検索し、該当するリクエストが記録されていないか確認する。
- GET /wp-json/wp/v2/users?per_page=100
- POST /wp-json/wplp-react-gdpr/v1/store-auth
- POST /wp-json/wplp-react-gdpr/v1/upload-logo
これらのリクエストがすべて記録されていれば、攻撃者がサイトに到達した証拠になる。アクセスログはサーバー会社の管理パネルや、レンタルサーバーのログ保存機能から取得できる。ログの保存期間が短いと痕跡が消えるため、普段から長めに保存する設定にしておくことが重要だ。
マルウェアスキャナーでファイルを検査する
サーバーに導入されているマルウェアスキャナーや、WordPress用のセキュリティプラグインを使って wp-content ディレクトリ全体をスキャンする。特に「*.jpg.php」のような二重拡張子のファイルや、最近改変されたPHPファイルが検出対象になる。
スキャナーは攻撃直後の未知のマルウェアを検出できないこともあるが、時間が経ってから見つかることも多い。複数のスキャナーを併用すると検出率が上がる。手動で確認する場合は、wp-content/uploads 以下のファイルで、画像に見せかけたPHPファイルが残っていないかを調べる。
テーマとプラグインの改ざんを確認する
攻撃者はすでに侵入に成功している場合、バックドアを別の場所に仕込んでいる可能性がある。アクティブなテーマの functions.php や、プラグインのディレクトリに不審なコードが追加されていないかを確認する。特に、難読化されたコードや、外部と通信する関数（file_get_contents、curl、eval など）が含まれている場合は注意が必要だ。
再発を防ぐための設定
今回の攻撃は特定のプラグインに依存しているが、同種の攻撃は他のプラグインでも発生する。サイト全体の防御力を上げるために、次の設定を検討する。
REST APIのユーザー一覧取得をブロックする
攻撃の第一段階では、WordPress標準のREST APIからユーザー一覧を取得して管理者のユーザー名を特定している。このエンドポイントを無効化するか、ログイン済みユーザーに限定すれば、攻撃の難易度を上げられる。
子テーマの functions.php に次のコードを追加すると、未認証のユーザー一覧取得を防げる。
add_filter( 'rest_endpoints', function( $endpoints ) {
if ( isset( $endpoints['/wp/v2/users'] ) ) {
unset( $endpoints['/wp/v2/users'] );
}
return $endpoints;
} );このコードはユーザー一覧のエンドポイントそのものを削除するため、ログイン中でも一覧を取得できなくなる。一部のプラグインがこの機能を使っている場合は影響を確認してから適用する。
アクセスログを長期間保存する
攻撃の痕跡は時間が経つと消える。サーバーのアクセスログを最低でも数週間、可能なら数ヶ月保存しておくと、侵害の調査や再発防止に役立つ。レンタルサーバーの標準設定では数日しか保存されないこともあるため、管理パネルやサーバー会社に確認して保存期間を延ばす。
プラグインの選定と更新ポリシーを見直す
Cookie同意プラグインに限らず、インストール数が少ないプラグインでも攻撃対象になる。更新が止まっているプラグインや、あまり知られていない開発元のプラグインを使い続ける場合は、代替手段を検討する。定期的にプラグインの更新を確認し、不要なプラグインは削除する。
よくある質問
WPLP Cookie Consentを使っていないが対策は必要か
今回の脆弱性はこのプラグイン固有のものだが、アップロードディレクトリでのPHP実行を拒否する設定や、REST APIのユーザー列挙対策はどのサイトでも有効な防御策になる。プラグインの更新とサーバー設定の見直しは、サイト全体のセキュリティを底上げする。
更新したのに攻撃された兆候が残っている場合はどうすればいいか
更新してもすでに設置されたマルウェアは消えない。不正な管理者アカウントの削除、マルウェアスキャン、テーマやプラグインの改ざん確認を行い、必要ならバックアップから復元する。確実なのは、クリーンなバックアップに置き換えて、全パスワードを再発行することだ。
アップロードディレクトリのPHP実行を拒否すると何か問題はあるか
通常のWordPressサイトでは、wp-content/uploads にPHPファイルを置く運用は推奨されていない。画像や文書の配信には影響しない。一部の特殊なプラグインやテーマがこの場所にPHPを置く場合は、事前に動作確認を行う。
REST APIを完全に無効化したほうがいいのか
完全な無効化は、ブロックエディタや一部の機能が動作しなくなるため現実的ではない。ユーザー一覧だけを狙ったエンドポイントを制限するか、認証を要求する設定が現実的な落とし所になる。
この記事のポイント
- WPLP Cookie Consent 4.4.1以前には未認証でファイルをアップロードされる脆弱性がある
- まずプラグインを4.4.2以上へ更新し、古いバージョンのままにしない
- wp-content/uploads 内のPHP実行をサーバー側で拒否する
- 不正な管理者アカウントがないか wp_users を確認する
- アクセスログとマルウェアスキャナーで侵害の痕跡を調査する
・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている
Product Feed PROでブランド・変動商品・商品カテゴリが出力されない時の直し方
Product Feed PRO for WooCommerceでブランド・変動商品・Google商品カテゴリがXMLに出力されない場合、まず確認すべきはフィールドマッピングの重複定義とキャッシュの遅延だ。症状が3つ同時に出ていても原因はそれぞれ別で、マッピング設定と条件設定を正しく組み替えれば大半は解決する。
ブランドがXMLに間欠的に出力される原因
同じブランドを割り当てた商品の一部にだけ<g:brand>が出力されない場合、最も多いのが「ブランドの取得ソースが複数存在している」ケースだ。WooCommerceの商品編集画面ではブランドが正しく見えていても、フィードプラグインは別のソースを参照して空の値を受け取ることがある。
Product Feed PROにはブランドを取得するための選択肢が複数用意されている。商品ブランド（product_brand）タクソノミー、商品属性（pa_brand）、YITH Brandプラグイン用の「Brand」、WooCommerce Brandsプラグイン用の「Product brand」などが代表だ。これらが混在していると、商品Aはタクソノミーから値を取得し、商品Bは未設定の商品属性を参照して空振りする、という動きになる。
特に複数のプラグインを併用していたり、過去にブランド管理の方法を変更したサイトで起きやすい。商品一覧のCSV書き出しでブランド列を確認すると、同じブランド名でも保存されている場所が商品によって異なるのがわかる。
商品B Dr Coffee → タクソノミーに設定済み → 属性は未設定 → 出力なし
商品B Dr Coffee → タクソノミーから取得 → 出力あり
このデモは、ブランドの取得ソースを属性にしたままタクソノミーのみ設定した商品で出力が欠落する状況を示している。対処は連載の後半でまとめて説明する。
商品ごとにブランドの保存場所を確認する
WooCommerceの商品一覧からCSVを書き出し、ブランドのタクソノミー列と属性列の両方を確認する。片方だけに値が入っている商品があれば、その商品群で出力が欠落しているはずだ。同じブランド名を保ったまま、フィードが参照するソースにデータを揃える必要がある。
フィードプラグインのフィールドマッピングを再定義する
フィードのフィールドマッピング画面で、<g:brand>フィールドの「取得ソース」を確認する。プルダウンに複数のブランド候補が並んでいたら、実際に価値が入っているタクソノミー（product_brand）を選択し直し、フィードを再生成する。
変動商品がフィードから完全に欠落する原因
変動商品（バリエーションを持つ商品）がXMLに一切出力されない場合、最初に確認するのは「デフォルトのバリエーション」の設定だ。WooCommerceの変動商品では「デフォルトのバリエーションを選択」プルダウンが「デフォルトを選択」のままになっていると、親商品がフィードの出力対象から外れることがある。
フィードプラグインの設定で「商品のバリエーションを含める」を有効にしても、親商品のバリエーション自体が正しく構築されていないと出力はできない。各バリエーションに価格・在庫状況・画像が設定されているか、親商品がカタログに表示される設定になっているかも重要なチェックポイントだ。
プルダウン「デフォルトを選択」のまま → フィード生成スキップ
バリエーション3点も非出力
プルダウンで1件選択 → フィードに親商品とバリエーションが出力
価格と在庫のある3バリエーションも表示
このデモは、デフォルトのバリエーション未選択で変動商品が出力から漏れる典型的なパターンを表している。ほかに価格未入力や在庫切れでも同様の欠落が起こる。
バリエーションの設定を一括で点検する
変動商品の編集画面で、各バリエーションに通常価格またはセール価格が登録されているか、在庫ステータスが「在庫あり」または「予約可能」になっているかを確認する。バリエーションが「非公開」や「カタログに表示しない」になっていないかも見る。
親商品の「商品データ」メタボックスでは、プルダウンで「デフォルトのバリエーション」を必ず1つ選ぶ。この操作が済んでいない変動商品は、フィードプラグイン側の設定に関係なく出力対象外になるケースが多い。
フィード設定の「商品のバリエーションを含める」を再確認する
Product Feed PROのフィード編集画面で、変動商品に関するオプションが有効か確認する。「商品のバリエーションを含める」と「親商品も含める」の両方が目に入るが、どちらか一方だけ有効になっていると期待した出力にならない。特に親商品を表示するには、その商品自体がカタログに表示される設定である必要がある。
Google商品カテゴリが出力されない原因
Google商品カテゴリ（<g:google_product_category>）がXMLに出ない場合、原因はほぼ「カテゴリマッピングの条件不一致」か「フィールドマッピングの取得ソースにgoogle_categoryが設定されていない」のどちらかだ。カテゴリマッピング画面でWooCommerceカテゴリとGoogleカテゴリを紐づけただけでは、フィードに反映されない。
カテゴリマッピングの画面では、左側にWooCommerceの商品カテゴリ、右側にGoogleの商品カテゴリを割り当てる。この割り当てが「すべてのカテゴリ」ではなく、一部のカテゴリだけに適用される条件で作られていると、対象外のカテゴリに属する商品からはカテゴリが出力されない。
→ 他のカテゴリ（ドリップ用品など）は
<g:google_product_category>が空のまま→ すべての商品に
<g:google_product_category>が出力このデモは、カテゴリマッピングの条件漏れで一部商品のGoogleカテゴリが空になる状況を示している。カテゴリマッピング画面は商品数が多いほど設定漏れが起きやすいので、全カテゴリを対象にするのが基本だ。
フィールドマッピングでgoogle_categoryが設定されているか確認する
フィードのフィールドマッピング画面で、Google側の<g:google_product_category>フィールドに対して、取得ソースが「google_category」になっていることを確認する。このソースは、カテゴリマッピング画面で定義した対照表を参照する専用の値だ。
誤って商品カテゴリそのものを割り当てていると、Googleが求める形式（例: Home & Garden > Kitchen & Dining > Coffee Makers）ではなく、WooCommerceのカテゴリ名だけが出力される。Google Merchant Center側でエラーまたは警告になるため、ソース設定は丁寧に見直す必要がある。
カテゴリマッピングを全カテゴリに適用する
カテゴリマッピング画面で、WooCommerceの各カテゴリに対応するGoogleカテゴリをすべて埋める。カテゴリが多い場合は「未マッピングのカテゴリ」フィルタを使うと、設定漏れのカテゴリだけを洗い出せる。親カテゴリを割り当てたら、子カテゴリが自動的に引き継がれるかどうかも確認する。
3つの問題をまとめて修正する手順
3つの問題が同時に起きている場合は、それぞれを個別に直すよりも、フィードの基本設定を順番に整える方が早い。次の手順でフィールドマッピング、変動商品設定、カテゴリマッピングを見直す。
このデモは、3つの症状をまとめて修正する際の優先順位を表している。ブランドの取得ソースを先に統一すると、変動商品とGoogleカテゴリの修正結果をXMLで正確に確認できる。
フィード再生成とキャッシュの扱い
設定を変更したあとは、フィードプラグインの「再生成」または「今すぐ更新」ボタンを実行する。WooCommerceやサーバー側のキャッシュが効いていると、更新前のXMLが表示され続けることがある。キャッシュプラグインを使っている場合は、フィードを再生成する前にキャッシュを削除すると確実だ。
生成されたXMLをブラウザで開き、<g:brand>、<g:google_product_category>、変動商品のIDやタイトルが表示されているかをCtrl+F（MacではCommand+F）で検索する。変動商品は親商品とバリエーションが別々の<item>要素として出力されるため、商品IDではなく商品名の一部で検索すると見つけやすい。
よくある質問
ブランドの出力が安定しないのはキャッシュが原因か？
キャッシュだけが原因になる場合は少ない。ブランドタクソノミーと商品属性の両方に同名のブランドが存在し、フィードのマッピングが不安定なソースを参照していることが多い。キャッシュを削除しても再発するなら、取得ソースの統一が先だ。
変動商品だけがXMLから消えるのはなぜか？
変動商品は親商品と各バリエーションが個別の商品として扱われるため、単純商品より出力条件が厳しい。デフォルトのバリエーション未選択、価格未入力、在庫切れ、または「商品のバリエーションを含める」設定のミスが典型的な原因になる。
Google商品カテゴリの出力形式が正しいか確認する方法は？
出力されたXML内の<g:google_product_category>の値を確認し、Google Merchant Centerが求める形式（不等号で区切られた英語の数字付きカテゴリパス）になっているかを見る。WooCommerceのカテゴリ名だけが入っている場合は、フィールドマッピングの取得ソースが誤っている。
設定を変えてもフィードが更新されない場合は？
フィードの再生成ボタンを押したあと、ブラウザでXMLを開いたときに古い内容が表示されることがある。キャッシュプラグインの削除、サーバー側のキャッシュ（OPcacheやVarnish）のクリア、またはクエリパラメータを付けて開く（例: feed.xml?nocache=1）と最新の出力を確認できる。
ブランドが空の商品はどうやって特定するか？
WooCommerceの商品一覧でフィルタ機能を使い、ブランドタクソノミーが空の商品を絞り込む。もし全商品にブランドが付いているのにXMLには一部しか出ていないなら、取得ソースの不一致を疑う。CSV書き出しでブランド列とブランド属性列を並べて比較すると特定しやすい。
この記事のポイント
- ブランドは取得ソースの統一が最優先
- 変動商品はデフォルトバリエーションの選択が必須
- Google商品カテゴリは全カテゴリのマッピングが必要
- 設定変更後はキャッシュを削除して再生成する
- XMLを検索して各フィールドの出力を検証する
・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている
カートページで数量を変更すると違う数になる時の対処法
WooCommerceのカートページで数量を1から2に変更したのに3が表示される不具合は、テーマまたはプラグインの古いJavaScriptが原因で数量更新のイベントが二重に処理されるケースが多い。まずテーマとWordPress本体・WooCommerceを更新し、それでも直らなければプラグインの競合を切り分けるのが最短の解決手順だ。
なぜカートページの数量変更で数がずれるのか
カートページで数量を変更すると、WooCommerceはAjax通信でサーバーに更新を送り、その結果を画面に反映する。このときブラウザ側のJavaScriptが「変更前の数量」と「変更後の数量」を正しく引き算して表示する仕組みになっている。
ところがテーマやプラグインが古いjQueryや独自のAjax処理を持っていると、同じクリックや入力イベントに対して数量加算の処理が2回走ることがある。たとえば「1を2に変更」が「1を3に変更」として解釈され、画面に3が表示される。
特に数量に小数を許可するプラグイン（WooCommerce Decimal Productなど）が有効な場合、数量フィールドの値の扱いが標準と変わるため、テーマ側のJavaScriptとの相性問題が表面化しやすい。プラグインを無効化すると正常になることから、原因がプラグイン単体でなく「プラグインとテーマの組み合わせ」にあると判断できる。
テーマとWordPressを最新版に更新する手順
この不具合は、テーマ・WordPress・WooCommerceのいずれかが古いことで、最近のブラウザやプラグインとの間でJavaScriptの仕様差が生じるために起きることがある。まずは更新作業から始める。
更新後はシークレットウィンドウや別ブラウザでテストする。通常のブラウザに古いCookieやキャッシュが残っていると、修正後も古いJavaScriptが動いてしまうためだ。
JavaScriptの競合を切り分ける手順
更新しても症状が変わらない場合、特定のプラグインやテーマのJavaScriptがWooCommerceの数量更新イベントと競合している。原因を特定するには「無効化テスト」が確実だ。
プラグインを1つずつ無効化して原因を特定する
まずプラグイン一覧から、数量に関係するプラグイン（小数プラグイン・カスタム数量プラグイン・Ajaxカートプラグインなど）を候補として絞り込む。それぞれ無効化してカートページを再読み込みし、数量が正しく更新されるか確認する。
もし特定のプラグインを無効化したときだけ正常になるなら、そのプラグインが原因だ。プラグインの更新版が出ていないか確認し、出ていなければ代替プラグインへの乗り換えを検討する。
ブラウザのコンソールでJavaScriptエラーを確認する
ブラウザのデベロッパーツール（ChromeではF12キー）を開き、「Console」タブを確認する。カートページで数量を変更したときに赤いエラーが表示される場合、エラーのファイル名から競合元を特定できる。
エラーメッセージが「jQuery is not defined」や「$ is not a function」なら、テーマのJavaScriptがjQueryを正しく読み込んでいない。wp_enqueue_script の順序や依存関係の問題なので、テーマ制作者に修正を依頼するか、子テーマ側で読み込みを調整する。
「cart-fragments」や「wc-cart-fragments」に関するエラーなら、WooCommerceのAjaxカート更新機能が別のプラグインと衝突している。該当プラグインを特定して無効化すれば症状は収まる。
キャッシュとCookieの影響を排除する
修正後も古い表示が続く場合は、サーバー側のキャッシュとブラウザ側のCookieが原因で古いJavaScriptが読み込まれている可能性がある。キャッシュプラグイン（WP Super Cache、W3 Total Cache、LiteSpeed Cacheなど）のキャッシュを全削除し、ブラウザのCookieとキャッシュも消去してから再テストする。
また、CDN（Cloudflareなど）を利用している場合は、CDN側のキャッシュもクリアする。CDNが古いJavaScriptファイルを配信し続けると、サーバー上では更新済みでもブラウザには古いコードが届く。
よくある質問
数量が正しく更新されるか確認する方法は？
カートページで数量を複数回変更し、そのたびにカート内の小計と合計が正しく再計算されるかを確認する。加えて管理画面の「WooCommerce→ステータス→ログ」にJavaScript関連のエラーが記録されていないか確認するとよい。
テーマを更新しても大丈夫？
更新前にバックアップを取っていれば問題ない。カスタマイズをテーマ本体に直接書いている場合は、更新で消える可能性があるので、子テーマや独自プラグインに移してから更新するのが安全だ。
小数プラグインを使い続けながら直す方法は？
プラグイン自体に更新版がない場合は、テーマ側のJavaScriptを修正して競合を回避する必要がある。具体的にはカートページの数量更新をWooCommerce標準のAjax処理に任せるよう、テーマのcustom.jsやmain.jsから数量関連のコードを除去する。
テストサイトを作るべき？
本番サイトに影響を与えずに原因を切り分けたい場合は、ステージング環境（多くのレンタルサーバーに標準搭載）か、ローカル環境（LocalやXAMPPなど）で同じテーマとプラグインを再現するのが有効だ。テストサイトで症状が再現できれば、切り分け作業を安全に進められる。
PHPのバージョンは関係ある？
PHPのバージョンが極端に古い（7.4未満など）場合、WooCommerceの最新版が正しく動作しないことがある。サーバー管理画面でPHP 8.0以上に更新できるか確認するのも有効な切り分けのひとつだ。
この記事のポイント
- カートの数量が「1→2」で「3」になるのはJavaScriptの二重処理が主因
- テーマ・WordPress・WooCommerceの更新で解決するケースが多い
- 直らない場合はプラグインを1つずつ無効化して競合元を特定する
- ブラウザとサーバーのキャッシュ・Cookie削除を忘れない
- 小数プラグインを使うならテーマ側のJavaScript競合を重点確認する
・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている
WP to Hootsuite 3.xで予約投稿が失敗するCronエラーの対処法
WP to Hootsuite を 3.x 系へ更新したあと、予約投稿が Hootsuite に公開されない場合は、Cron クラスの reschedule_refresh_token_event メソッドが未定義のままになっている可能性が高い。プラグインを 3.1.4 以降へ更新すれば、この致命的エラーは解消する。
なぜWP to Hootsuite 3.xで予約投稿が失敗するのか
この不具合は、プラグインの更新時に必要なメソッド定義がファイルへ正しく反映されず、呼び出しだけが先に組み込まれた状態で発生する。3.x 系では WPZinc 製プラグイン共通の Social ライブラリへ構成が変わったため、一部のファイルに古いコードと新しいコードが混在しやすくなっている。
具体的には、includes/functions.php が Cron クラスの reschedule_refresh_token_event メソッドを呼ぶ一方、lib/social/includes/class-cron.php にそのメソッド定義がない。存在しないメソッドへの呼び出しは PHP の致命的エラーを引き起こし、その後の処理が止まる。
WPZinc\Social\Cron::reschedule_refresh_token_event()予約投稿の実行は WP-Cron（WordPress の予約実行システム）を経由する。ここで致命的エラーが起きると画面には何も表示されず、プラグイン自身のログ画面にも記録が残らない。管理画面からの手動更新はトークン再スケジュール処理を通らないため成功するので、問題の特定が遅れやすい。
上の図は、予約投稿が致命的エラーで止まるまでの流れを示している。
プラグインのログ画面が空のままなのは、致命エラーが起きた時点で PHP の処理が停止し、ログを書き込むコードまで到達しないためだ。管理画面からの手動更新ではトークン再スケジュール処理が呼ばれないため、問題なく成功する。
3.1.4以降への更新で解消する手順
この不具合はプラグイン側のコード不整合なので、特別な設定変更は不要だ。WP to Hootsuite を 3.1.4 以上へ更新すると、未定義だったメソッドが class-cron.php に追加され、予約投稿の処理が最後まで走るようになる。
更新作業の前に、必ずサイト全体のバックアップを取る。プラグイン更新そのものは数分で終わるが、万一テーマや他プラグインと競合した場合に戻せる状態にしておくことが重要だ。
上のステップは、更新から動作確認までの一連の流れを示している。
更新後はキャッシュ系プラグインの全削除も忘れずに行う。そのうえで、以前に失敗した投稿を一度下書きへ戻すか、公開予定日時を再設定して様子を見ると確実だ。
すぐに更新できない場合はどう対処するか
2.x系へ巻き戻して様子を見る
何らかの事情ですぐに 3.1.4 へ更新できない場合は、動作していた 2.x 系へ巻き戻すのが安全だ。WP Rollback などのプラグインを使うか、FTP で該当プラグインのフォルダを旧バージョンに差し替える。ただし、旧バージョンには以降のセキュリティ修正が含まれない点には注意が要る。
手動公開に切り替えて一時運用する
致命的エラーは予約投稿の実行時に発生するため、更新が終わるまで予約投稿を避け、公開したいタイミングで管理画面から手動で公開する運用も現実的な選択だ。下書きのまま用意しておき、公開直前に「公開」ボタンを押す流れにすると、サイト運営を止めずに済む。
ステージング環境で先に検証する
本番サイトへの更新が不安な場合は、ステージング環境（本番と同構成の検証用サイト）で先に 3.1.4 を適用し、予約投稿のテストを行う。これにより、他プラグインとの競合や認証トークンの再連携が必要かどうかを事前に確認できる。
デバッグログで原因を特定する手順
プラグインのログ画面に何も残らない場合、PHP のデバッグログを有効にすると致命的エラーの内容が確認できる。本番サイトでは通常エラー表示が無効化されているため、管理画面にも何も出ない。
wp-config.php に次の記述を追加すると、エラー内容が wp-content/debug.log に書き込まれる。あらかじめ FTP または管理画面のテーマファイルエディタから wp-config.php を開いておく。
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);設定後にテスト用の予約投稿を実行し、wp-content/debug.log を確認する。未定義メソッドの場合、「Call to undefined method」（未定義メソッドの呼び出し）という趣旨のエラーが残る。日本語環境でも PHP の内部エラーは英語で記録される。確認後は、WP_DEBUG を false に戻してログ出力を止める。
よくある質問
3.1.4に更新しても予約投稿が失敗する場合は？
まずバージョン表記を確認し、本当に 3.1.4 以上へ置き換わったかを確かめる。そのうえでキャッシュを全削除し、Hootsuite との認証を一度解除して再接続する。それでも改善しない場合は、他プラグインとの競合を切り分ける。
更新ボタンが出てこない場合は？
プロ版や一括購入版では、管理画面の自動更新が効かないことがある。WPZinc の配布ページから最新版をダウンロードし、FTP で該当フォルダを上書きする。上書き前には必ずバックアップを取る。
WP-Cronが正しく動いているか確認するには？
WP Crontrol などのプラグインで予約イベントの一覧を確認し、投稿公開のイベントが登録されているかをチェックする。WP-Cron 自体が停止している場合は、サーバー側の cron 設定や wp-config.php の ALTERNATE_WP_CRON 設定を見直す必要がある。
デバッグログが出力されない場合は？
wp-content フォルダの書き込み権限が不足している可能性がある。FTP で wp-content のパーミッションを確認し、debug.log が作成できる状態か確かめる。あわせて、キャッシュ系プラグインやセキュリティプラグインが wp-config.php の変更をブロックしていないかも確認する。
2.xへ戻してもいいか？
一時的な回避として 2.x 系へ戻すのは有効だが、セキュリティ更新が含まれないため恒久対応にはならない。できるだけ早期に 3.1.4 以降へ更新し、検証のうえで運用を戻すのが望ましい。
この記事のポイント
- 3.x 更新後に予約投稿が止まる原因は、呼び出しだけ存在する未定義メソッドによる致命的エラー
- プラグインのログが空でも、PHP のデバッグログを有効にすれば原因が見える
- 更新版 3.1.4 以降では Cron クラスのメソッド定義が揃い、予約投稿が正常に動く
- すぐ更新できない場合は 2.x へ巻き戻すか、手動公開で一時運用する
- 更新前のバックアップと、ステージング環境での事前検証が再発防止につながる
・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている
WordPress 7.1でサイトエディターが真っ白になる原因と直し方
WordPress 7.1に更新した後、サイトエディター（wp-admin/site-editor.php）だけが真っ白になる場合は、ブラウザの互換性とJavaScriptエラーを最初に確認し、それでも解決しなければサーバーエラーログとREST APIの応答を調べる。サイトエディターは投稿編集画面と比べてJavaScriptとREST APIへの依存度が高く、原因はこの2系統に集中している。
なぜサイトエディターだけが真っ白になるのか
サイトエディターは、テンプレートやテンプレートパーツ、グローバルスタイルと呼ばれるデザイン設定を、REST API経由でサーバーから取得してJavaScriptで描画する。投稿編集画面が正常でも、サイトエディターだけが真っ白になるのは、この特殊な描画経路のどこかでエラーが起きているためだ。
主な原因は次の4つに分けられる。
- 古いブラウザが最新JavaScript機能に対応していない
- JavaScriptファイルの読み込み失敗や例外が起きている
- REST APIが内部エラーを返してテンプレート情報を取得できない
- PHPのメモリ不足で致命的エラーが発生している
真っ白な画面の原因切り分けは、この4ステップの順で行うと効率的だ。
古いブラウザが原因かどうかを確認する手順
最初に確認するのはブラウザの互換性だ。サイトエディターはブロックエディターと同じく、最新のJavaScript機能をフルに使って動作する。Firefox ESRや数世代前のSafari、旧バージョンのChromeでは、これらの機能に対応できずに画面全体が真っ白になることがある。特に長期的にブラウザをアップデートしていない業務用端末や古いノートPCで起こりやすい。
確認方法はシンプルで、同じサイトを別の端末や別のブラウザで開いてみる。もし最新版のChrome、Edge、Firefoxのいずれかで正常に表示されるなら、使用中のブラウザが古いことが原因だ。その場合はブラウザのアップデートを行うか、対応ブラウザに切り替える。どうしても古いブラウザで作業しなければならない場合は、サイトエディターの使用を避け、投稿編集画面から個別のテンプレートを編集するという回避策もある。
デベロッパーツールでJavaScriptエラーを確認する
最新ブラウザでも真っ白になる場合は、デベロッパーツール（開発者ツール）を開いてJavaScriptエラーを調べる。画面が真っ白になる症状の多くは、レンダリングを途中で止めるJavaScriptの例外や、重要なファイルの読み込み失敗が直接の原因になっている。
ChromeやEdgeではF12キー、MacではCommand+Option+Iキーでデベロッパーツールが開く。Firefoxでは右クリックから「要素を調査」を選ぶとよい。開いたら「コンソール」タブに切り替え、ページを再読み込みする。コンソールに赤い文字で表示されるエラーを上から順に確認する。
TypeErrorやReferenceError、SyntaxErrorの表示があれば、それが画面描画を止めている例外だ。また「Failed to load resource」のようなエラーは、必要なJavaScriptファイルが読み込めていないことを示す。この場合は更新時にファイルが欠損した可能性が高いため、後述するWordPress本体の再インストールで解決することが多い。
サーバーエラーログとREST APIを確認する
ブラウザ側に明確なJavaScriptエラーが見つからない場合、次にサーバー側の状態を確認する。サイトエディターはREST API経由でテンプレート情報を取得するため、サーバーでエラーが発生していても画面上には何も表示されず、真っ白なままになる。
サーバーのエラーログを確認するときは、サイトエディターを開いた直後の時刻に注目する。エラーログには過去のボットスキャンや他のリクエストも大量に記録されている。AH01276のようなDirectoryIndex関連のエラーは、多くの場合ボットがディレクトリを直接スキャンした痕跡であり、エディターの真っ白とは無関係だ。ログを上から眺めるのではなく、症状が起きた時刻に新しいエントリが追加されたかどうかを確認する。
サーバーログと並行して、REST APIが正しく応答するかを直接チェックする。ブラウザのアドレスバーに自分のサイトURLに続けて wp-json/wp/v2/templates と入力して開いてみる。正常ならテンプレート一覧の入ったJSONデータが表示される。ここでエラーページやHTTP 500系のエラーが返るなら、REST API側に問題がある。
PHPメモリ上限と再インストールで直す
確認した内容に応じて対処する。PHPのメモリ不足を示すエラー（Allowed memory size of から始まるFatal error）がログに記録されている場合は、メモリ上限を引き上げる。デフォルトの128Mでは、テンプレートの多いサイトや高機能テーマでサイトエディターの読み込み中に不足することがある。wp-config.phpに次の1行を追加するか、レンタルサーバーの管理画面からメモリ上限を変更する。
define('WP_MEMORY_LIMIT', '256M');エラーログにメモリ不足が出ていない場合や、ブラウザのコンソールにファイル読み込みエラーが出ている場合は、WordPress本体の再インストールが有効だ。ダッシュボードの「更新」メニューを開き、「WordPressを再インストールする」ボタンを押す。wp-admin、wp-includes、ルートのコアファイルが最新版で上書きされ、更新時に欠損したファイルが復元される。テーマやプラグイン、投稿データには影響しない。
再インストール後も症状が続く場合は、一度標準テーマ（Twenty Twenty-Fiveなど）に切り替えてサイトエディターが開くか確認する。標準テーマで開くなら使用中のテーマ側に原因があり、標準テーマでも開かないならサーバー設定やREST APIの応答に原因が残っている可能性が高い。
よくある質問
プラグインをすべて無効化しても直らないのはなぜか
サイトエディターの真っ白はプラグインの競合だけでなく、ブラウザ、JavaScript、REST API、PHPメモリなど複数の要因が絡む。特にREST API経由のデータ取得に失敗している場合はプラグイン無効化だけでは切り分けが不十分だ。ブラウザのコンソールとサーバーログの両方を確認する必要がある。
同じブラウザなのにサイトによって動作が違うのはなぜか
サイトごとに使用中のテンプレートやブロック、グローバルスタイルの構成が異なる。古いブラウザが対応していないJavaScript機能を使うブロックや設定が含まれているサイトだけが真っ白になる。また、サイトごとのメモリ上限やサーバー設定の違いも影響する。
WordPress 7.0に戻した方がよいか
セキュリティ修正を含む更新を戻すのは推奨しない。WordPress 7.1のまま原因を特定して解決する方が安全だ。原因を切り分ける手順を踏めば、ロールバックせずに直せるケースがほとんど。
デベロッパーツールが使えない端末ではどうすればいいか
別の端末やブラウザで同じサイトを開いて症状を再現し、そこからデベロッパーツールやサーバーログを確認する。どうしても別端末が用意できない場合は、サーバーエラーログを症状発生直後の時刻で確認し、PHPの致命的エラーやREST APIの応答を調べるとよい。
この記事のポイント
- サイトエディターの真っ白はブラウザ互換性を最初に疑う
- デベロッパーツールでJavaScriptエラーを特定する
- サーバーエラーログは症状が起きた直後の時刻で確認する
- REST APIの応答を直接チェックして切り分ける
- PHPメモリ不足なら上限を引き上げる
- ファイル欠損が疑わしい場合はWordPress本体を再インストールする
・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている
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と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制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている
hCaptcha 5.2.0更新後にログインできない時の対処法とダウングレード手順
hCaptcha プラグインを 5.2.0 に更新した直後からログイン画面に「Bad hCaptcha signature!」と表示され、管理画面へ入れない場合は、5.1.0 へのダウングレードと全キャッシュの削除で解決する。この不具合は 5.2.0 の署名検証リグレッションが原因で、サイトキーやシークレットキーの設定ミスではない。
なぜhCaptcha 5.2.0への更新後にログインエラーが起きるのか
hCaptcha 5.2.0 はログイン時の署名形式を変更している。署名とは、データが改ざんされていないことを証明する値のことだ。この変更が原因で署名検証フローにリグレッション（回帰不具合、以前は正常だった機能が更新によって壊れること）が混入した。
WordPress のログイン統合と別のログイン統合が、同じ wp-login.php エンドポイントを通じて送信される際に署名の検証が失敗する。複数のプラグインがログイン画面に同時に作用する構成で、この問題が顕著に現れる。
「Bad hCaptcha signature!」というエラーは、プラグインがローカルで生成している。hCaptcha API にリクエストを送る前の段階で発生するため、サイトキーとシークレットキーの検証が成功していてもエラーが消えない。この点が原因の切り分けを難しくしている。
「ログイン試行前のhCaptcha」の設定値を 0 にしている場合、この不具合はすべてのログイン試行で発生する。0 に設定すると署名検証を回避する余地がなくなり、毎回エラーに遭遇する。
ログイン不能な状態から管理画面へ入る手順
管理画面に入れない状態でも、FTP や SSH でサーバーへ接続すれば hCaptcha プラグインを一時停止できる。プラグインを停止するとログイン経路が確保されるため、その後は通常どおり管理画面へアクセスできる。
この手順で管理画面へ入り、ダウングレードの準備を整える。
FTPまたはSSHでプラグインを停止する
FTP クライアントでサーバーへ接続し、wp-content/plugins ディレクトリへ移動する。hcaptcha というフォルダを見つけたら、フォルダ名を「hcaptcha-disabled」のように変更する。WordPress はプラグインを読み込まなくなるため、ログイン画面からキャプチャが消えて通常のログインフォームが表示される。
SSH を使える環境なら、wp-content/plugins ディレクトリで mv コマンドを実行する方法が速い。コマンドラインでの操作に慣れている場合は、この選択肢が確実だ。
管理画面に入ったらhCaptcha設定を確認する
プラグインを停止してログインできたら、WordPress 管理画面の「プラグイン」を開く。hCaptcha が停止状態になっていることを確認し、これから行うダウングレードに備えて現在の設定メモを残しておくとスムーズだ。
hCaptcha 5.2.0を5.1.0へダウングレードする手順
管理画面へ入れるようになったら、hCaptcha 5.2.0 を削除して 5.1.0 をインストールする。設定データは削除しても保持されるため、サイトキーとシークレットキーを再入力する必要はない。
5.1.0 へ戻すと署名検証の不具合が解消され、ログインできるようになる。
5.2.0を削除して5.1.0をインストールする
WordPress 管理画面の「プラグイン」から hCaptcha 5.2.0 を削除する。削除しても設定はデータベースのオプションテーブル（デフォルトでは wp_options）に残るため、サイトキーやシークレットキーが消えることはない。
次に 5.1.0 の ZIP ファイルを公式リポジトリなどから入手する。「プラグイン」メニューの「新規追加」を開き、「プラグインのアップロード」から ZIP ファイルを選択してインストールする。インストール完了後に有効化する。
サイトキーとシークレットキーを再確認する
インストール後、hCaptcha の設定画面を開き、サイトキーとシークレットキーに値が入っていることを目視で確認する。5.2.0 から戻しても設定は残っているはずだが、念のため両方のフィールドをチェックしておく。
キーの検証ボタンを押して成功すれば、API との通信自体は正常ということだ。ただしこの不具合は通信前にローカルで発生するため、検証成功の表示が出ても油断はできない。あくまでキーの有効性を確認するだけの操作だと理解しておく。
モードをLiveに設定して保存する
設定画面でモードが Live になっていることを確認し、変更があれば保存する。サイズが invisible になっているかも確認する。設定を保存したら、次のキャッシュ削除の手順へ進む。
キャッシュを削除してエラーを完全に解消する
バージョンを 5.1.0 に戻しただけではエラーが残ることがある。5.2.0 が署名形式を変更した影響で、以前のバージョンが生成したログイン HTML が各種キャッシュに残っていると、同じエラーが引き続き表示される。
ページキャッシュとサーバーキャッシュを削除する
使用しているキャッシュプラグイン（WP Super Cache や W3 Total Cache など）の管理画面を開き、ページキャッシュとオブジェクトキャッシュを削除する。サーバー側のキャッシュ機能（Varnish や LiteSpeed Cache など）が有効な場合も、同じく削除操作を行う。
CDNのキャッシュを削除する
Cloudflare やその他の CDN を利用している場合、CDN の管理画面からキャッシュをパージする。ログインページの HTML がエッジサーバーに残っていると、WordPress 側の設定が正しくても古い署名形式のページが配信され続ける。
プライベートウィンドウで動作確認する
キャッシュ削除後、通常のブラウザタブではなくプライベートウィンドウ（シークレットウィンドウ）でログインページを開く。ブラウザのローカルキャッシュや Cookie も残っていると、修正後のページを正しく読み込めないことがある。
プライベートウィンドウでログインを試み、キャプチャを通過して管理画面に入れればダウングレードは成功だ。通常のブラウザタブでまだエラーが出る場合は、ブラウザのキャッシュと Cookie を個別に削除して再試行する。
自動更新を止めて再発を防ぐ
修正版がリリースされるまで、自動更新で 5.2.0 に戻らないようにしておく。プラグインの自動更新は個別に無効化できるため、hCaptcha だけ更新を止めておくのが安全だ。
hCaptchaの自動更新を無効化する
WordPress 管理画面の「プラグイン」一覧で hCaptcha の行を確認し、自動更新を無効にする。プラグインごとの自動更新設定はプラグイン一覧画面から切り替えられる。WordPress 本体の自動更新とは別の設定なので、本体は更新を継続したまま hCaptcha だけを固定できる。
修正版のリリースを確認する方法
プラグインの公式ページやリポジトリを定期的に確認し、5.2.1 以降の修正版がリリースされたかをチェックする。修正版が出るまでは 5.1.0 のまま運用し、更新前には必ずテスト環境でログイン動作を確認する。
本番環境へ修正版を適用する際も、まずステージング環境でログイン、キャプチャ表示、ユーザー登録、パスワードリセットの一連の動作を検証してからリリースするのが安全だ。
よくある質問
プラグインを削除するとhCaptchaの設定は消えますか
いいえ、消えない。プラグインを削除しても設定はデータベースに保持される。アンインストール時にデータを削除するクリーンアップ設定を事前に有効化していた場合のみ、削除される仕組みだ。ダウングレードでサイトキーを再入力する必要はない。
ダウングレード後に「インストールが不正です」と表示されます
5.2.0 から 5.1.0 へ手動で戻す際、WordPress が古いバージョンのインストールを「不正」と判定することがある。この場合は一度 5.2.0 を完全に削除してから 5.1.0 を新規インストールする。設定が残っているため、再設定の手間はかからない。
サイトキーとシークレットキーの検証は成功するのにエラーが続きます
「Bad hCaptcha signature!」は、プラグインが API へリクエストを送る前のローカル段階で生成される。キーの検証は API との通信が正常であることを示すだけで、署名検証の不具合とは無関係だ。そのためキーが正しくてもエラーは消えない。
ログイン時にキャプチャテストが表示されるのは正常ですか
「サイズ」を「invisible」に設定しているにもかかわらず画像選択テストが表示される場合、設定が正しく反映されていない可能性がある。ダウングレード後にキャッシュを削除し、プライベートウィンドウで再度確認するとよい。それでも表示される場合は、ログイン試行前の設定値や他のログイン系プラグインとの競合を調べる。
自動更新で勝手に5.2.0に上がるのを防げますか
防げる。WordPress 管理画面の「プラグイン」一覧から hCaptcha の自動更新を個別に無効化できる。また、複数のプラグインを一元管理している場合は、更新ポリシーで hCaptcha を除外する設定を行う。
この記事のポイント
- 5.2.0 の署名検証リグレッションがログインエラーの原因
- エラーはAPI通信前のローカル処理で発生する
- 5.1.0 へのダウングレードが確実な対処法
- プラグイン削除後も設定データは保持される
- 全キャッシュ削除とプライベートウィンドウでの確認が必須
・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている
ForminatorでStripe決済は通るのに送信履歴が残らない時の対処法
Forminator のフォームに必須の Stripe 決済フィールドを設置したサイトで、カード決済は成功しているのに送信履歴（エントリー）が保存されず、管理者への通知メールも届かない場合は、ページキャッシュとフォーム保存処理の競合をまず疑うべきだ。「AJAX を使用してフォームを読み込む」を有効にし、送信後のリダイレクトを一時的に外して切り分けるのが最短の対処になる。
なぜ Stripe 決済は成功するのにフォーム送信履歴が残らないのか
送信ボタンを押すと、Stripe への決済実行と、WordPress データベースへのエントリー保存という2つの処理がほぼ同時に走る。この2つは経路が完全に独立しているため、片方だけが成功する状態が起こり得る。決済は Stripe の画面で完結するが、送信履歴の保存は WordPress 側のセキュリティトークン（nonce）検証を通らないと書き込まれない。
このデモは、決済が成功してもフォーム保存だけが別経路で失敗する仕組みを示している。保存に失敗する典型的な原因は、ページキャッシュに取り残された古いセキュリティトークンだ。フォームの HTML が静的キャッシュとして配信されると、トークンの有効期限が切れたまま送信され、非同期保存だけが拒否される。
送信後に別の URL へリダイレクトする設定にしている場合は、保存処理が終わる前にページ遷移が始まり、データベースへの書き込みが中断されることがある。3D Secure（本人認証）でカード会社の認証画面を挟む決済では、フォームへ戻ってから保存が再開されるため、この競合が断続的に発生しやすい。
まず「AJAX を使用してフォームを読み込む」を有効にする
Forminator のフォーム編集画面を開き、「動作」タブ（英語環境では Behavior）の「レンダリング」セクションに「AJAX を使用してフォームを読み込む」チェックボックスがある。これが無効のままだと、フォームの HTML がそのままキャッシュされ、トークン劣化の引き金になる。
このオプションを有効にすると、フォーム部分だけが非同期で最新の状態に置き換わる。キャッシュされたページにアクセスしても、フォーム内部のトークンはその都度更新され、送信履歴の保存処理が正しく通る。設定を保存したら、必ずサイトのページキャッシュをクリアしてから動作確認する。
既に有効にしていても症状が出る場合はどこを確認する？
チェックが既に付いていた場合は、AJAX 読み込みだけでは競合を防ぎきれていない。次に、送信後のリダイレクトを一時停止して症状が消えるか確認する。それでも直らない場合は、Stripe 側の本人認証フローとキャッシュの二重がけを順に調べる。
送信後のリダイレクトを一時停止して切り分ける
Forminator の「送信後動作」（英語環境では After Submission Behavior）設定では、複数の動作を追加しても先に登録した1つだけが処理される。インラインメッセージのあとにリダイレクトを設定していた場合は、実質インラインメッセージだけが動いていた状態になる。そこからリダイレクトだけに変えると、保存完了を待たずにページが遷移し、送信履歴が残らなくなることがある。
このデモのように、まずリダイレクト設定を外してインラインメッセージだけにし、数回テスト送信する。これで全ての送信履歴が残れば、リダイレクトが引き金になっていたと判断できる。
リダイレクトを使いたい場合はどうすればいい？
保存処理を追い越さない順序に組み直す必要がある。具体的には、まずインラインメッセージで送信完了を知らせ、その画面からページ遷移する導線にする。これが難しい場合は、当面リダイレクトなしで運用し、症状が出ないことを確認してから設定を戻す。保存処理の完了を待たずに遷移させる構成は、たとえ短い間隔でも断続的な欠損を招く。
3D Secure（本人認証）経由の決済かどうかを確認する
Stripe の 3D Secure（カード会社がワンタイムパスワードやアプリ認証を求める仕組み）が発動する取引では、認証画面や銀行アプリへの切り替えが入る。この認証が終わってフォーム画面に戻るとき、Forminator 側の保存処理が正しく再開されず、決済だけ記録される事例がある。
まず Stripe ダッシュボードの「支払い」から該当の取引を検索し、決済金額と顧客情報が残っているか確認する。決済は残っているのにフォームのエントリーだけ欠損している場合、症状が一致する。続けて、症状が特定のカードブランドや発行会社に偏っていないかを支払い方法別に絞り込む。3D Secure の認証フローが絡む場合は、Forminator と Stripe の API 連携上の問題になるため、プラグインを最新版へ更新した上で、フォームのエクスポートを開発元サポートに渡して再現確認を依頼する。
キャッシュプラグインとフォームページを除外設定にする
サイトでページキャッシュを使っている場合は、フォームを設置しているページをキャッシュ対象外にする。特に決済フォームのある固定ページやランディングページは、静的な HTML 配信をやめて、常に WordPress が生成する最新の画面を返す設定にする。
利用しているキャッシュプラグインの除外設定で、対象ページの URL パスや、フォームの ID を含むクエリを指定する。あわせて、ログイン状態のユーザーにはキャッシュを返さない設定が有効かも確認する。サーバー側のキャッシュ（共用サーバーの高速化機能など）が二重にかかっている場合は、管理画面やホスティングの設定から該当ページのキャッシュを無効化する。これで、AJAX 読み込みを有効にしていても起きる断続的な症状を防げる。
よくある質問
Stripe の決済が通っているのに送信履歴が残らないのはなぜ？
決済と送信履歴の保存は別経路で処理されている。ページキャッシュでフォームのセキュリティトークンが古くなると、決済は Stripe 側で成功しても、WordPress 側のエントリー保存だけが拒否されることがある。送信後のリダイレクトが保存処理を追い越すのも原因の一つだ。
AJAX 読み込みを有効にするとデザインや表示速度に影響はあるか？
フォームの HTML が非同期読み込みに変わるため、ページ表示後すぐにフォームが出ず、一瞬だけ空の枠が出ることがある。見た目はほとんど変わらず、速度も体感できる差はない。キャッシュされたページとの相性は大幅に改善する。
送信履歴が残っていないのに決済は成功している場合、二重請求を防げるか？
顧客が送信を繰り返すと二重決済のリスクがある。該当期間の Stripe ダッシュボードで同一顧客の複数決済を確認し、重複が疑われる場合は返金対応を行う。フォーム側では二重送信防止の設定を確認しておく。
送信履歴が消えた分のデータは復元できるか？
WordPress のデータベースに送信エントリーが書き込まれていないので、Forminator の管理画面上では復元できない。一方、Stripe 側には支払いデータが残っているため、決済情報と顧客メールアドレスを照合して注文内容を再構成することになる。メール通知が届いていない分は、Stripe のレシートが顧客との連絡手段になる。
決済後に送信履歴が残らない確率はなぜ回によって違うのか？
ページキャッシュの状態とトークンの有効期限の関係で、キャッシュが新しければ保存が通り、古ければ失敗する。3D Secure の認証が挟まる場合は、戻り方のタイミングでさらにバラつく。そのため同じフォームでも数回に1回だけ失敗するような断続的な症状になる。
この記事のポイント
- Stripe 決済と送信履歴の保存は別経路で処理される
- まず「AJAX を使用してフォームを読み込む」を有効にしてキャッシュ競合を減らす
- 送信後のリダイレクトを一時停止して保存処理の追い越しを切り分ける
- 3D Secure が絡む決済かどうかを Stripe ダッシュボードで確認する
- フォーム設置ページをキャッシュ対象外にして再発を防ぐ
・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている
WooCommerceで小数数量の購入が通らない時の原因と対処法
WooCommerceのチェックアウトで小数数量（1.5kgや0.8mなど）を指定すると、line_itemsパラメータが無効というエラーが表示され、注文が完了できなくなる。原因はWooCommerceのデフォルト仕様でカート内の数量が整数として扱われるため。数量単位を変えて整数にするか、小数数量対応のプラグインを導入すれば解決できる。
なぜWooCommerceで小数数量を購入できないのか
WooCommerceの商品数量フィールドは、標準状態では1、2、3といった整数しか受け付けない。ところが、計量販売や布地・配線材など小数単位で売りたい商品は多く、小数を入力できるよう改造したサイトも存在する。
問題が表面化するのは、チェックアウトブロックを使っている場合だ。このブロックはStore APIと呼ばれるREST APIを通じて注文データをサーバーに送る。Store APIは送られてきた注文明細（line_items）を検証する際に、数量を整数としてチェックする。ここで小数が混ざっていると「line_itemsパラメータが無効」というエラーを返す。
従来のクラシックチェックアウト（ショートコード方式）では別の仕組みで注文を送るため、同条件でもエラーが出ないことがある。つまり「カートには小数で入るのに、チェックアウトブロックだけ失敗する」という症状になりやすい。
このデモは、小数数量がAPI検証で拒否される流れと、単位を変換して整数にした場合の成功フローを示している。エラーの根本原因はフロント側の表示ではなく、APIが受け取る数量の形式にある。
数量単位を変えて整数だけで販売する手順
もっとも手軽で確実な方法は、商品の販売単位そのものを細かくして、顧客が常に整数で数量を入力できるようにする方法だ。たとえば1.5kgの商品を売るなら、販売単位を「kg」から「100g」に変更し、顧客には15と入力してもらう。
食品・重量商品の場合
コーヒー豆や精肉、チーズなど重量で売る商品では、単位をグラムに切り替えるだけで解決できる。商品名に「100gあたり」と明記し、価格も100g単位で設定する。1.5kg買いたい顧客は数量欄に15と入力すればよい。
布地・ロープ・配線材の場合
メーター単位で切売りする商品は、センチメートル単位に変換するのが有効だ。1.5mは150cmとして、数量欄には150と入力してもらう。商品タイトルに「1cm単位で販売」と明記すれば混乱も防げる。
在庫管理とSKUの見直し
単位を変えたら在庫数とSKUも新しい単位に合わせて更新する必要がある。1kgの在庫は1000gとして記録し、SKUも単位が分かる番号に変更しておくと後の運用が楽になる。既存の注文データには影響しないので、商品単価と在庫だけを慎重に更新する。
小数数量対応のプラグインで解決する方法
どうしても小数数量を維持したい場合は、小数数量に対応したプラグインを導入する方法がある。WooCommerce公式のエクステンションストアには、数量の刻み幅を小数で設定できる拡張が複数配布されている。
プラグインを選ぶ際の確認ポイントは、次の3点だ。まず、チェックアウトブロック（Store API）に対応していること。フロント側の数量入力だけを変更しても、API検証で拒否されれば同じエラーが再発する。次に、在庫管理でも小数を扱えること。最後に、WooCommerceの最新バージョンで動作確認されていること。
導入後は、商品編集画面に小数ステップの設定欄が追加される。数量の刻み幅を0.1に設定し、最小数量も小数で指定する。設定を保存したら、必ずテスト注文で小数数量が通るか確認する。カートに入れる段階とチェックアウト実行の両方でエラーが出ないことを確かめる。
開発者向けカスタムコードで数量の小数を許可する方法
自作テーマやカスタムプラグインで対応する場合は、数量入力フィールドの引数をフィルターで変更する。以下のコードは、テーマのfunctions.phpやCode Snippetsプラグインに追加する想定だ。
add_filter( 'woocommerce_quantity_input_args', 'allow_decimal_quantity', 10, 2 );
function allow_decimal_quantity( $args, $product ) {
$args['step'] = '0.1';
$args['min_value'] = '0.1';
return $args;
}ただし、このコードだけではフロント側の入力欄が小数に対応するだけで、Store APIの検証までは通過しないことがある。チェックアウトブロックを使う場合は、API側のスキーマを拡張する追加のフィルターが必要になる。Store APIのline_itemsで数量の型を変更するには、より深い層への対応が求められる。
実務では、Store API対応を自前で実装するより、小数数量対応をうたうプラグインを利用する方がリスクが小さい。APIスキーマの変更はアップデートで挙動が変わる可能性があり、受注データの整合性にも関わるためだ。
小数数量が必要な商品の販売方法を再設計する
エラーの対処と並行して、そもそも小数数量を使わずに済む販売設計を検討するのも有効だ。商品の性質によっては、属性（バリエーション）を使う方がシンプルで顧客にも分かりやすい。
よく買われるサイズをバリエーションで用意する
布地やケーブルなら「50cm」「1m」「1.5m」「2m」のように、よく注文されるサイズをあらかじめバリエーションとして登録する。顧客は数量1を選ぶだけで済み、小数入力は不要になる。在庫管理も単位が明確になるため、発注ミスも減らせる。
計量販売プラグインの活用
重量や長さに応じて価格を自動計算する計量販売向けの拡張を使う手もある。顧客が重さや長さを入力すると、対応する価格が自動で表示される仕組みだ。この方式なら小数数量を直接カートに入れる必要がなく、エラーの発生を回避できる。
よくある質問
小数数量を使うと必ずこのエラーになりますか
いいえ。従来のクラシックチェックアウト（ショートコード方式）では、フロント側で小数を許可していれば通ることがある。エラーが起きやすいのはチェックアウトブロックを使っており、Store API経由で注文を送信する構成だ。
商品ごとに小数数量を許可できますか
できる。小数数量対応プラグインの多くは商品単位で設定を持っており、小数を許可する商品と整数のみの商品を混在させられる。カスタムコードでも商品IDやカテゴリを条件にフィルターを適用できる。
数量単位をgに変更すると在庫管理はどうなりますか
在庫数も新しい単位に合わせて記録し直す必要がある。1kgの在庫は1000gとして登録し、SKUも単位が分かる体系に変更するのが望ましい。既存の注文履歴には影響しないため、商品単価と在庫数を慎重に更新すればよい。
すでに小数数量で登録した商品がある場合はどうすればよいですか
商品データを確認し、数量の刻み幅や単位設定を見直す。複数商品を一括で変更するなら、WooCommerce標準の商品CSVエクスポート・インポート機能を使うと効率的だ。変更後はテスト注文で必ず動作を確認する。
チェックアウトブロックだけでエラーになるのはなぜですか
チェックアウトブロックはStore APIというREST API経由で注文データをサーバーに送信する。このAPIがline_itemsを検証する際、数量を整数としてチェックするため、小数が混ざると検証エラーになる。クラシックチェックアウトは別の送信方式のため、同じ条件でも通ることがある。
この記事のポイント
- 小数数量の購入エラーはStore APIのline_items検証が原因
- もっとも手軽な対処は数量単位を変えて整数で販売すること
- 小数数量を維持したい場合は対応プラグインの導入が有効
- チェックアウトブロック対応の有無を確認してからプラグインを選ぶ
- カスタムコードはフロント側だけでは不十分でAPI側の対応も必要
- 属性や計量販売方式への再設計も検討価値がある
・ Reddit、Stack Overflow、WordPress.org フォーラムを日々巡回し、現場の悩みを拾い上げて記事化
・ WordPress、WooCommerce、Next.js などモダンWeb制作領域のトラブルシューティングが専門
・ 「検索しても答えが見つからなかった」を一つでも減らすことが目標
・ エラーメッセージから根本原因にたどり着く粘り強い調査が得意
・ 初心者がつまずきやすい箇所を先回りで解決する記事作りを心がけている