タグアーカイブ WordPress

WP All Importで物件画像が混ざる原因とファイル名の一意化による解決方法

WP All Import で物件情報をインポートした際、他の物件の画像が表示される不具合は、画像ファイル名の重複と画像マッチング設定の不備が主な原因だ。この問題は、WP All Import のファイル名指定で一意の名前を生成し、画像マッチングルールを適切に設定することで解決できる。

WP All Import でインポートした画像が混ざる原因は何か

WP All Import は XML フィードから画像をダウンロードし、メディアライブラリに追加する。ここで「すでに同じファイル名の画像がメディアライブラリに存在する」と、意図せず既存の画像を参照してしまうことがある。特に検索やマッチングをすべてオフにしていても、ファイル名の衝突が発生すると新規ダウンロードをスキップして既存画像にリンクを張る挙動が起こりうる。これが、異なる物件で同じ画像が表示される最大の原因だ。

もう一つの原因は、Houzez テーマやそのアドオンがインポート後に画像ギャラリーを再構築する際、メディアライブラリ内の添付ファイルの親子関係やメタデータを誤って上書きしてしまうケースだ。プレビュー段階では正しいのに、インポート完了後に別の物件の画像に差し替わるのは、インポート後のテーマ側の処理タイミングで画像の紐付けがずれるために起こる。

画像ファイル名を一意にして他物件との画像混入を防ぐ方法

WP All Import では、インポートテンプレートの「画像」セクションで、保存時のファイル名をカスタマイズできる。ここで物件ごとに絶対に重複しない名前を付けるのが最も確実な対策だ。具体的には、物件 ID や MLS 番号、住所の一部など、XML 内のユニークな要素をファイル名に組み込む。

上のデモのように、{mls_id} や {property_id} といった絶対に重複しないフィールドをファイル名に含める。インポート時に「既存画像を保持」の設定をオフにしていても、ファイル名が重複すると WordPress 本体側で「ファイル名-1」「ファイル名-2」のように連番サフィックスが付与されることがあり、このサフィックス付きファイル名を Houzez アドオンが正しく追跡できない場合もある。ファイル名の段階で完全にユニークにしておけば、そのリスクも回避できる。

WP All Import の画像マッチング設定を適切に構成する

現在「すべてオフ」の状態は、一見すると毎回新規ダウンロードされそうに見えるが、実際にはファイル名の重複や WordPress の内部キャッシュによって想定外のマッチが起こりうる。以下の設定を見直す。

画像 URL またはファイル名でのマッチを有効にする

「Match image by URL」をオンにすると、WP All Import は XML 内の画像 URL とメディアライブラリ内の元 URL メタデータを照合し、すでに同じ URL からダウンロードされた画像があれば再利用し、なければ新規ダウンロードするという明確な挙動になる。「すべてオフ」よりも意図が明確で、混入が防ぎやすい。

Search Media Library for existing images の使い所

この設定は、ファイル名やタイトルで既存画像を検索する。ファイル名が重複しがちな構成ではオフのままが安全だが、ファイル名を一意にしたうえでオンにすれば、再インポート時の二重ダウンロードを防ぎつつ正確にマッチできる。画像ファイル名の一意化が完了しているなら、ここをオンにして「既存画像の検索」に任せるのも選択肢になる。

First image set as Featured Image の副作用に注意する

この設定がオンの場合、WP All Import と Houzez アドオンがそれぞれ「アイキャッチ画像」を設定しようとして、2つの処理が干渉することがある。画像の入れ替わりが激しいなら、いったんこの設定をオフにして、Houzez アドオン側にアイキャッチ設定を任せてみる。それで安定するなら、アドオン側の処理が優先される構成に統一する。

Houzez アドオンとテーマ側の画像処理を確認する

Houzez アドオンはインポート後に物件ギャラリーやアイキャッチ画像を再構成する独自の処理を行う。この処理が WP All Import のメディアライブラリ操作と競合し、別の物件の画像を拾ってしまうことがある。特に再インポート時に、アドオンが「物件に紐づく既存画像」を誤ったロジックで上書きするパターンが報告されている。

アドオンの画像処理フックを一時停止して検証する

子テーマの functions.php に以下のコードを一時的に追加し、Houzez アドオンの画像処理をスキップしてインポート結果が正しくなるかテストする（テスト後は必ず削除する）。

// テスト用 インポート後の Houzez 画像処理を無効化
add_action('init', function() {
    if (class_exists('Houzez_Property_Feed')) {
        remove_all_actions('pmxi_after_xml_import');
        remove_all_actions('pmxi_saved_post');
    }
}, 99);

これで画像の混入が止まるなら、Houzez アドオン側の処理が原因だ。その場合、アドオンの最新バージョンへのアップデート、または Houzez 公式サポートに「WP All Import インポート後の画像上書き」の修正を依頼する。アドオンのバージョンが古いと、WP All Import の最新 API との互換性が崩れていることがある。

再インポート前にメディアライブラリの紐付けをリセットする

WP All Import で「既存の投稿を更新」する形で再インポートする場合、過去のインポートで作られたメディアの紐付け（post_parent やメタデータ）が残っていると、新しい画像が正しく割り当てられない。この場合は、一度該当の物件投稿と画像の紐付けを手動で外すか、WP All Import 実行前に該当物件の画像をメディアライブラリから削除してから再インポートすると、クリーンな状態で画像が再構築される。

Amazon S3 Offload 使用時の画像混入を防ぐ

Amazon S3 Offload（WP Offload Media 等）を使用している場合、メディアライブラリの画像実体は S3 に移動され、ローカルにはメタデータだけが残る。この状態で WP All Import が「同じファイル名」の画像を処理しようとすると、S3 上の URL とメディアライブラリのメタデータに不整合が生じ、参照がずれることがある。

S3 Offload の URL 書き換えタイミングを確認する

WP Offload Media はアップロード後に URL を書き換えるが、このタイミングが WP All Import のインポート後処理や Houzez アドオンのギャラリー構築タイミングと重なると、書き換え前のローカル URL が一時的に保存されてしまう。S3 Offload プラグインが「非同期処理」や「スケジュール処理」で URL を更新する設定になっているなら、同期処理に切り替えて、インポート完了までにすべての URL が書き換わるようにする。

インポート中は S3 Offload を一時停止する

大量インポート時は、WP Offload Media のアップロードフックを一時的に停止して、WP All Import のインポートが完全に終わったあとに手動で一括オフロードする方法も有効だ。インポートスクリプトの先頭でオフロードを無効化し、完了後に再有効化するワークフローにすると、混入リスクをほぼゼロにできる。

よくある質問

Preview では正しいのに本番インポートで画像が混ざるのはなぜか

Preview は実際のダウンロードとメディアライブラリ登録をスキップし、XML の URL だけを表示する仕組みだ。本番インポートではメディアライブラリへの保存が行われ、このときにファイル名衝突やテーマの後処理が発動して画像が入れ替わる。この違いが「Preview では正しいのに本番で壊れる」現象の正体だ。

画像が混ざった物件を一括で修正できるか

WP All Import の「既存の投稿を更新」機能を使い、画像フィールドだけを再インポートすることで一括修正できる。その際、ファイル名の一意化とマッチング設定の見直しを事前に済ませておく必要がある。メディアライブラリに重複画像が大量にある場合は、一度不要画像を一括削除してから再インポートすると確実だ。

Houzez テーマ以外でも同じ問題は起こるか

起こる。WP All Import とテーマ付属の独自インポートアドオンが競合する構図は、不動産テーマ（HomePress、RealHomes 等）や EC（WooCommerce の WP All Import アドオン）でも報告されている。基本的な対策であるファイル名の一意化とマッチング設定の見直しは、どのテーマでも有効だ。

画像 URL にクエリパラメータが付いている場合の注意点はあるか

URL の末尾に ?w=800&h=600 のようなパラメータが付いていると、WP All Import が「別の画像」として認識せず、パラメータ部分を無視してファイル名を生成するため重複が起きやすい。URL マッチングを使用する場合も、パラメータ除去後のベース URL で照合されるため、意図したマッチが働かないことがある。可能なら XML 側でクエリパラメータのないクリーンな URL を用意するのが望ましい。

メディアライブラリの画像が増えすぎないか心配だ

ファイル名の一意化と画像 URL マッチングを適切に設定すれば、同じ URL の画像はメディアライブラリに一度だけ保存されて再利用される。重複ダウンロードが起きていたのは、ファイル名衝突によって新規保存と既存参照が混在していたためで、設定を見直せばメディアライブラリの肥大化も抑えられる。

この記事のポイント

• 画像混入の主因はファイル名重複とマッチング設定の不備
• XML 内のユニーク ID をファイル名に組み込む
• 画像 URL マッチングをオンにして明確な挙動にする
• Houzez アドオンの画像処理競合はフック停止で検証
• S3 Offload 使用時は同期処理への切り替えが安全

佐々木 太陽

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