中級Web制作者がハマるWordPressの技術的なトラブルTOP10

SOSブログ
  1. はじめに：中級者が直面する、より複雑な課題
  2. 一目でわかる：中級者がハマるWordPressトラブルTOP10と解決の核心
  3. ①N+1クエリ問題：気づきにくいパフォーマンス低下の原因
    1. どんなトラブル？
    2. なぜ起こるの？
    3. どうすれば解決できる？
  4. ②コアウェブバイタルの悪化：体感速度だけではない、Googleの評価指標
    1. どんなトラブル？
    2. なぜ起こるの？
    3. どうすれば解決できる？
  5. ③巨大化するfunctions.phpの整理
    1. どんなトラブル？
    2. なぜ起こるの？
    3. どうすれば解決できる？
  6. ④カスタム投稿タイプの404エラー：リライトルールの更新忘れ
    1. どんなトラブル？
    2. なぜ起こるの？
    3. どうすれば解決できる？
  7. ⑤admin-ajax.phpのパフォーマンス問題
    1. どんなトラブル？
    2. なぜ起こるの？
    3. どうすれば解決できる？
  8. ⑥メールの到達性問題：フォームの通知が届かない
    1. どんなトラブル？
    2. なぜ起こるの？
    3. どうすれば解決できる？
  9. ⑦HTTPS移行後の混合コンテンツエラー
    1. どんなトラブル？
    2. なぜ起こるの？
    3. どうすれば解決できる？
  10. ⑧自作コードのセキュリティ脆弱性
    1. どんなトラブル？
    2. なぜ起こるの？
    3. どうすれば解決できる？
  11. ⑨データベース移行の失敗とシリアライズデータ
    1. どんなトラブル？
    2. なぜ起こるの？
    3. どうすれば解決できる？
  12. ⑩WordPressマルチサイト特有の課題
    1. どんなトラブル？
    2. なぜ起こるの？
    3. どうすれば解決できる？
  13. 結論：パターンを理解し、エキスパートへ
    1. コナン先生のWebトラブル何でも相談窓口

はじめに：中級者が直面する、より複雑な課題

WordPressの基本操作に慣れ、カスタム投稿タイプの実装や、テーマやプラグインのカスタマイズができるようになると、Web制作者として大きな自信がつくでしょう。

しかし、経験を積むにつれて、これまでとは異なる、より複雑な問題に直面することがあります。

駆け出しの頃は、まず「動くこと」が目標でした。

駆け出しWeb制作者がハマるWordPressの技術的なトラブルTOP10
多くの駆け出しWebデザイナーやクリエイターが、キャリアの初期段階で必ずと言っていいほど直面するのが、「なぜか動かない」「さっきまで動いていたのに」という不可解な技術的トラブルの壁です。
conan.live
2025.09.27

しかし中級レベルになると、書いたコードがサイトのパフォーマンスにどう影響するか、セキュリティ上のリスクはないか、そして将来のメンテナンスは容易か、といった点まで考慮する必要があります。

開発環境では問題なかったのに、本番環境でコンテンツが増えるとサイトが遅くなる。SSL化したのに「保護されていない通信」と表示される。こうした問題は、多くのWeb制作者が経験する課題です。

この記事では、中級者が直面しがちなWordPressの10の技術的トラブルを厳選し、その根本原因と具体的な解決策を解説します。

ここで取り上げるのは、単なるエラーではなく、WordPressの内部構造やWeb開発のベストプラクティスへの理解を深める上で重要な、繰り返し発生する問題の「パターン」です。

これらのパターンを理解し乗り越えることは、単に問題を解決するだけでなく、パフォーマンス、セキュリティ、拡張性を考慮できる開発者へと成長するための重要なステップとなるでしょう。

一目でわかる：中級者がハマるWordPressトラブルTOP10と解決の核心

詳細な解説に入る前に、この記事で取り上げる10の技術的トラブルとその解決策の要点を一覧で示します。現在直面している問題のクイックリファレンスとしてご活用ください。

トラブル陥りがちな状況（シナリオ）解決の核心（原則）主要な関数・ツール
1. N+1クエリ問題コンテンツが増えるにつれて、投稿ループの処理が極端に遅くなる。多数の小さなクエリではなく、一つの効率的なクエリで関連データを先読みする。update_post_meta_cache, オブジェクトキャッシュ (Redis), Transients API
2. コアウェブバイタルの悪化サイトは体感的に速いのに、Google Search Consoleで「不良URL」と報告される。ページの主要コンテンツの表示を優先し、読み込み時のレイアウトのズレを防ぐ。JS/CSSの遅延読み込み, font-display: swap, 画像サイズの指定
3. 巨大化するfunctions.phpテーマのfunctions.phpが、管理不能なほど雑多なコードで肥大化する。機能に関するコードとデザインに関するコードを分離し、論理的な単位に整理する。サイト専用プラグイン, include/require, Code Snippetsプラグイン
4. カスタム投稿タイプの404エラー新しく追加したカスタム投稿タイプのアーカイブや個別ページが404エラーになる。投稿タイプ登録後、WordPress内部のURL書き換えルールを強制的に再生成させる。flush_rewrite_rules() (有効化時), パーマリンクの再保存
5. admin-ajax.phpのボトルネックAJAXを多用した機能が、サーバーに高負荷をかけ、応答が遅くなる。非同期リクエストを、重いadmin-ajax.phpから軽量なREST APIへ移行する。register_rest_route, permission_callback, wp_create_nonce
6. メールの到達性問題フォームの通知やユーザー登録メールが届かない、または迷惑メールになる。サーバーのデフォルト機能ではなく、専用のSMTPサービス経由でメール送信を認証する。WP Mail SMTPプラグイン, SendLayer, Brevo, Mailgun
7. 混合コンテンツエラーHTTPSへ移行したサイトで、ブラウザに「保護されていない」という警告が表示される。すべてのアセット（画像、スクリプト、スタイルシート）を確実にHTTPS経由で配信する。ブラウザ開発者ツール (コンソール), WP-CLI search-replace, Really Simple SSL
8. 自作コードの脆弱性自作テーマやプラグインが、意図せずXSSなどのセキュリティホールを生んでしまう。ユーザー入力を決して信用せず、入力時に検証・サニタイズし、出力時にエスケープする。sanitize_*(), wp_kses_post(), esc_*(), $wpdb->prepare()
9. データベース移行の失敗データベースを移行する際、URLの置換によってサイトの表示や設定が壊れる。シリアライズ化されたPHPデータをインテリジェントに処理するツールを使用する。WP-CLI search-replace, --dry-run, --skip-columns=guid
10. WordPressマルチサイトの落とし穴マルチサイトがプラグイン競合やクッキーエラーで不安定になる。ネットワークインストールの共有リソースと特有の設定を理解し、適切に管理する。ネットワークレベルのデバッグ, wp-config.phpの定数設定

①N+1クエリ問題：気づきにくいパフォーマンス低下の原因

どんなトラブル？

「イベント」というカスタム投稿タイプの一覧ページを実装したとします。WP_Queryを使い、ループ内で各イベントの開催地（カスタムフィールド）やカテゴリー（カスタムタクソノミー）を表示します。

テストデータが10件程度の開発環境では問題なく動作しますが、500件のデータが登録された本番環境では、ページの表示が極端に遅くなってしまいました。

なぜ起こるの？

このパフォーマンス低下の原因は、「N+1クエリ問題」と呼ばれる、データベースへの問い合わせ回数が意図せず増加してしまう現象です。

まず、WP_Queryでイベント一覧を取得するために1回のデータベースクエリが実行されます。しかし、その後のループ処理で、取得したN件の投稿それぞれに対してget_post_meta()（カスタムフィールド取得）やget_the_terms()（ターム情報取得）を呼び出すたびに、追加のクエリが発生してしまいます。

もし500件のイベントがあれば、合計で 1+500+500=1001 回ものクエリが実行されることになり、サーバーに大きな負荷がかかります。

この問題は、データ量が少ない開発環境では表面化しにくいため、見過ごされがちです。

どうすれば解決できる？

解決策は、ループ内で個別にデータを取得するのではなく、事前にまとめて取得しておく「事前読み込み」という考え方に基づいています。

解決策1：WP_Queryのパラメータでキャッシュを事前準備する

WP_Queryのパラメータに 'update_post_meta_cache' => true と 'update_post_term_cache' => true を追加します。

これにより、WordPressはメインのクエリ実行後、取得した全投稿IDを使って、関連するメタデータとターム情報を効率的な追加クエリでまとめて取得し、キャッシュに保存します。

その後のループ内でget_post_meta()やget_the_terms()を呼び出しても、キャッシュからデータが読み込まれるため、データベースへの追加クエリは発生しません。

問題のあるコード例：

PHP

$args = array(
    'post_type'      => 'event',
    'posts_per_page' => 50,
);
$events_query = new WP_Query( $args );

if ( $events_query->have_posts() ) {
    while ( $events_query->have_posts() ) {
        $events_query->the_post();
        // ループのたびにDBクエリが発生する可能性がある
        $location = get_post_meta( get_the_ID(), 'event_location', true );
        $categories = get_the_terms( get_the_ID(), 'event_category' );
        //...
    }
}

最適化されたコード例：

PHP

$args = array(
    'post_type'              => 'event',
    'posts_per_page'         => 50,
    'update_post_meta_cache' => true, // メタデータのキャッシュを有効化
    'update_post_term_cache' => true, // タームのキャッシュを有効化
);
$events_query = new WP_Query( $args );

if ( $events_query->have_posts() ) {
    while ( $events_query->have_posts() ) {
        $events_query->the_post();
        // キャッシュからデータを取得するため、追加クエリは発生しない
        $location = get_post_meta( get_the_ID(), 'event_location', true );
        $categories = get_the_terms( get_the_ID(), 'event_category' );
        //...
    }
}

解決策2：永続オブジェクトキャッシュの導入

WordPressの標準オブジェクトキャッシュは、1回のリクエスト内でのみ有効です。RedisやMemcachedといった外部ツールを導入し、「永続的オブジェクトキャッシュ」を構築すると、複数リクエスト間でキャッシュデータを保持できるため、サイト全体のデータベース負荷をさらに削減できます。

導入には「Redis Object Cache」のようなプラグインが便利です。

解決策3：Transients APIによる部分的なキャッシング

「人気の記事ランキング」のように、リアルタイム性が必須ではないが処理が重いクエリには、Transients APIが有効です。

set_transient()で有効期限付きのデータを保存し、get_transient()で取得します。これにより、指定した期間（例：1時間）はデータベースに問い合わせることなく、キャッシュから高速にデータを返すことができます。

Transients APIの利用例：

PHP

function get_popular_events_widget_data() {
    $popular_events = get_transient( 'popular_events_widget' );

    if ( false === $popular_events ) {
        $args = array( /*...重いクエリのパラメータ... */ );
        $query = new WP_Query( $args );
        $popular_events = $query->posts;
        set_transient( 'popular_events_widget', $popular_events, HOUR_IN_SECONDS );
    }

    return $popular_events;
}

N+1クエリ問題への対処は、単に「動くコード」を書くだけでなく、「パフォーマンスを意識したコード」を書くための重要なステップです。

必要なデータをいかに効率的に取得するかを考えることで、より高度な開発スキルが身につきます。

②コアウェブバイタルの悪化：体感速度だけではない、Googleの評価指標

どんなトラブル？

パフォーマンス改善のためにキャッシュプラグインを導入し、サイトの体感速度は非常に速くなりました。

しかし、Google Search Consoleを見ると、コアウェブバイタル（Core Web Vitals）レポートで多くのURLが「改善が必要」または「不良」と評価されています。この評価は検索順位にも影響するため、無視できません。

なぜ起こるの？

この問題は、サイトの「速さ」の指標が、サーバーの応答時間だけでなく、ユーザー体験を重視するようになったために起こります。

コアウェブバイタルは、Googleが定めるユーザー体験の質を測る指標で、主に以下の3つで構成されます。

  1. LCP (Largest Contentful Paint / 最大コンテンツの描画)
    • 内容： ページの主要コンテンツが表示されるまでの時間。読み込み速度を測ります。
    • 目標値： 2.5秒未満
  2. CLS (Cumulative Layout Shift / 累積レイアウトシフト)
    • 内容： ページの読み込み中にレイアウトが予期せずずれる度合い。視覚的な安定性を測ります。
    • 目標値： 0.1未満
  3. INP (Interaction to Next Paint / 次の描画までのインタラクション)
    • 内容： ユーザーがクリックなどの操作をしてから、画面が反応するまでの時間。応答性を測ります。
    • 目標値： 200ミリ秒未満

キャッシュプラグインはLCPの改善に役立ちますが、CLSやINPといったフロントエンド側の問題には、追加の対策が必要です。

どうすれば解決できる？

コアウェブバイタルの改善には、サーバーサイドとフロントエンドの両方からのアプローチが求められます。

LCPの改善

  • レンダーブロッキングリソースの排除
    必須でないCSSやJavaScriptの読み込みを遅らせ、主要コンテンツの描画を優先させます。functions.phpでscript_loader_tagフィルターフックを使い、スクリプトタグにdeferやasync属性を付与します。
  • サーバーと配信の最適化
    高速なホスティングの利用、CDN（コンテンツデリバリーネットワーク）の導入、サーバーでの圧縮（GZIPなど）の有効化が基本です。

CLSの改善

  • 画像とiframeにサイズを指定する
    すべての<img>タグや<iframe>タグにwidthとheight属性を指定します。これにより、ブラウザはメディアが読み込まれる前に適切なスペースを確保でき、レイアウトのズレを防ぎます。
  • Webフォントの最適化
    @font-face宣言にfont-display: swap;を追加します。これにより、カスタムフォント読み込み中に代替フォントでテキストを先に表示し、レイアウトのズレを最小限に抑えます。

    CSS

    @font-face {
    font-family: 'MyCustomFont';
    src: url('/fonts/my-custom-font.woff2') format('woff2');
    font-display: swap; /* この一行が重要 */
    }

INPの改善

  • JavaScriptの実行を最適化する
    INP悪化の主な原因は、重いJavaScript処理です。WP RocketやPerfmattersのようなパフォーマンス改善プラグインを利用すると、JavaScriptの遅延読み込み（Defer）や実行遅延（Delay）を簡単に設定でき、改善が見込めます。

パフォーマンスは、開発の最終段階で追加するものではなく、設計段階から考慮すべき重要な品質です。

コアウェブバイタルの最適化は、サーバーサイドからフロントエンドまで、幅広い知識が求められる総合的な課題と言えます。

③巨大化するfunctions.phpの整理

どんなトラブル？

プロジェクトのfunctions.phpが、気づけば数千行を超えていました。

カスタム投稿タイプの登録、ショートコード、AJAX処理、スクリプトの読み込みなど、様々なコードが混在し、管理が非常に困難になっています。

一行の修正ミスがサイト全体をダウンさせるリスクも抱えています。

なぜ起こるの？

functions.phpは手軽にカスタムコードを追加できるため、多くの開発者が長期的な設計を考えずにコードを追記しがちです。

これが技術的負債となり、メンテナンス性を著しく低下させます。

どうすれば解決できる？

肥大化したfunctions.phpを整理し、メンテナンスしやすい構造にするには、いくつかの方法があります。

解決策1：ファイルを機能ごとに分割する

最も手軽な方法は、コードを機能ごとに別のファイルに分割することです。テーマ内にincなどのフォルダを作成し、post-types.phpやshortcodes.phpといったファイルにコードを分けます。

そして、functions.php本体からこれらのファイルをrequireで読み込みます。

これにより、functions.phpは見通しが良くなります。

functions.phpの記述例：

PHP

// 機能ファイルを読み込む
require get_template_directory(). '/inc/post-types.php';
require get_template_directory(). '/inc/shortcodes.php';

解決策2：サイト専用プラグインへ切り出す

より本質的な解決策は、「機能」に関するコードをテーマから分離することです。

カスタム投稿タイプのようなサイトの根幹に関わる機能は、テーマではなくプラグインに記述するべきです。そうすることで、将来テーマを変更しても機能が失われる心配がありません。

サイト専用プラグインの作成は簡単です。

  • PC上にプラグイン用のフォルダ（例：my-site-functionality）を作成します。
  • 中に同名のPHPファイル（例：my-site-functionality.php）を作成し、ファイルの先頭にプラグイン情報を示すヘッダーコメントを記述します。
  • functions.phpから機能関連のコードをこのファイルに移動します。
  • フォルダをzip圧縮し、WordPress管理画面からプラグインとしてアップロード・有効化します。

解決策3：Code Snippetsプラグインを活用する

小さなコード片を管理するには、「Code Snippets」プラグインが非常に便利です。

このプラグインを使うと、各コードを個別に有効化／無効化でき、テーマを変更してもコードは維持されます。また、コードに構文エラーがあってもサイト全体がダウンするのを防いでくれます。

functions.phpの整理は、単なるファイル整理ではありません。「どこにコードを配置するか」という設計思想が、プロジェクトの長期的な成功を左右します。

「関心の分離」というソフトウェア工学の基本原則を実践する良い機会です。

④カスタム投稿タイプの404エラー：リライトルールの更新忘れ

どんなトラブル？

register_post_type()関数を使って新しいカスタム投稿タイプ「製品（product）」を追加しました。

管理画面では問題なく製品を登録できますが、サイトのフロントエンドで製品の個別ページやアーカイブページにアクセスすると、「404 Not Found」エラーが表示されてしまいます。

なぜ起こるの？

この問題の主な原因は、WordPressが内部で保持しているURLの書き換えルール（リライトルール）が更新されていないためです。

新しいカスタム投稿タイプをコードで追加しただけでは、WordPressは/product/のような新しいURL構造を認識できず、ページが見つからないと判断して404エラーを返します。

どうすれば解決できる？

リライトルールを更新し、WordPressに新しいURL構造を認識させるには、いくつかの方法があります。

解決策1：管理画面からパーマリンク設定を再保存する

最も簡単で確実な方法です。

  1. 管理画面の「設定」>「パーマリンク設定」に移動します。
  2. 設定内容は何も変更せず、ページ下部の「変更を保存」ボタンをクリックします。

この操作だけで、WordPressはリライトルールを再構築し、新しいカスタム投稿タイプのURL構造を反映させます。

解決策2：flush_rewrite_rules()を適切に使う

テーマやプラグインとして機能を配布する場合、コードでリライトルールを更新する必要があります。そのための関数がflush_rewrite_rules()です。

ただし、この関数は負荷が高いため、ページの読み込みごとに実行してはいけません。プラグインの有効化時など、一度しか実行されないタイミングで呼び出すのが正しい使い方です。

プラグイン有効化時にリライトルールを更新するコード例：

PHP

// プラグインのメインファイルに記述

// カスタム投稿タイプを登録する関数
function my_plugin_register_post_type() {
    // register_post_type() の処理...
}
add_action( 'init', 'my_plugin_register_post_type' );

// プラグインが有効化された時に一度だけ実行
function my_plugin_activate() {
    my_plugin_register_post_type();
    flush_rewrite_rules();
}
register_activation_hook( __FILE__, 'my_plugin_activate' );

この問題は、コードを追加するだけでなく、WordPressの内部状態を更新する必要があることを示しています。

APIの表面的な使い方だけでなく、内部メカニズムへの理解を深めることが重要です。

⑤admin-ajax.phpのパフォーマンス問題

どんなトラブル？

商品一覧ページにリアルタイム検索機能を実装しました。

ユーザーが文字を入力するたびに、jQueryのAJAXを使ってadmin-ajax.phpにリクエストを送り、結果を動的に表示します。

機能は動作しますが、入力のたびにサーバーのCPU使用率が上がり、サイト全体のレスポンスが遅くなります。

なぜ起こるの？

この問題の原因は、WordPressの伝統的なAJAXの窓口であるadmin-ajax.phpの仕組みにあります。

admin-ajax.phpへのリクエストは、たとえ小さなデータを取得するだけであっても、処理のためにWordPressのコア、有効な全プラグイン、テーマを読み込みます。

これは非常に非効率で、特にリクエストが頻繁に発生する機能では、サーバーに大きな負荷をかけます。

どうすれば解決できる？

現代的なアプローチは、admin-ajax.phpの使用をやめ、より軽量なWordPress REST APIへ移行することです。

解決策：軽量なREST APIへの移行

WordPress REST APIを使えば、WordPressのコア全体を読み込むことなく、特定の機能（エンドポイント）だけを呼び出せます。これにより、応答速度が向上し、サーバー負荷も大幅に軽減されます。

独自のREST APIエンドポイントは、register_rest_route関数を使って作成します。

admin-ajax.phpを使った従来の実装（PHP）:

PHP

add_action( 'wp_ajax_my_live_search', 'my_live_search_callback' );
add_action( 'wp_ajax_nopriv_my_live_search', 'my_live_search_callback' );

function my_live_search_callback() {
    check_ajax_referer( 'my_search_nonce', 'security' );
    //...検索処理...
    wp_send_json_success( $results );
}

REST APIを使った現代的な実装（PHP）:

PHP

add_action( 'rest_api_init', function () {
    register_rest_route( 'myplugin/v1', '/search', array(
        'methods'  => 'GET',
        'callback' => 'my_rest_search_callback',
        'permission_callback' => '__return_true', // 誰でもアクセス可能
    ) );
} );

function my_rest_search_callback( $request ) {
    //...検索処理...
    return new WP_REST_Response( $results, 200 );
}

JavaScript側では、/wp-json/myplugin/v1/searchのようなエンドポイントURLを直接呼び出します。

セキュリティ：権限チェックとNonce

REST APIでは、セキュリティもより柔軟に扱えます。

  • 権限チェック (permission_callback)
    エンドポイントごとに、誰がアクセスできるかを細かく制御できます。
  • NonceによるCSRF対策
    ログインユーザー向けの操作では、wp_create_nonce('wp_rest')で生成したNonceをリクエストヘッダーに含めることで、安全性を確保できます。

admin-ajax.phpからREST APIへの移行は、単なるパフォーマンス改善だけでなく、WordPress開発をよりモダンなアーキテクチャへと進化させるプロセスです。

⑥メールの到達性問題：フォームの通知が届かない

どんなトラブル？

お問い合わせフォームを設置しましたが、クライアントから「問い合わせ通知が全く届かない」という報告を受けました。

また、別のサイトでは「ユーザー登録の確認メールが迷惑メールフォルダに入ってしまう」という問題が発生しています。

なぜ起こるの？

この問題の原因は、WordPressが標準で使うメール送信方法にあります。

wp_mail()関数は、通常、ホスティングサーバーのPHPのmail()関数を利用しますが、この方法には信頼性の問題があります。

  • 認証の欠如
    この方法で送信されるメールは、送信元が正当であることを証明する認証情報（SPF、DKIMなど）を持っていません。
  • 信頼性の低さ
    Gmailなどの主要なメールサービスは、認証されていないメールをスパムと判断し、受信をブロックしたり、迷惑メールフォルダに振り分けたりします。

つまり、問題はWordPressのバグではなく、その送信方法が現代のセキュリティ基準を満たしていないためです。

どうすれば解決できる？

解決策は、信頼できる外部のSMTP（Simple Mail Transfer Protocol）サービスを利用してメールを送信するようにWordPressを設定することです。

解決策：WP Mail SMTPプラグインによる認証済みメール送信

最も確実な方法は、「WP Mail SMTP by WPForms」プラグインを導入することです。このプラグインは、WordPressからのメール送信を、指定した外部のSMTPサービス経由で行うように中継してくれます。

設定手順の概要：

  • WP Mail SMTPプラグインのインストール
    WordPress管理画面からプラグインをインストールし、有効化します。
  • SMTPメーラーサービスの選択とアカウント作成
    SendLayer、Brevo (旧Sendinblue)、Mailgunなど、メール送信を代行してくれるサービスを選び、アカウントを作成します。多くは無料プランを提供しています。
  • WP Mail SMTPの設定
    プラグインの設定ウィザードに従い、ステップ2で選んだサービスを選択し、APIキーなどの認証情報を入力します。送信元メールアドレスには、サービスで認証したドメインのメールアドレスを設定します。
  • テストメールの送信
    設定完了後、プラグインのテスト機能でメールを送信し、正常に受信トレイに届けば設定完了です。

この問題の解決は、サイト内部のコードだけでなく、メール認証のような外部のルールや標準にも準拠する必要があることを示しています。

専門的なタスクを外部の専門サービスに委ねるという、現代的なWeb開発の基本を学ぶ良い機会です。

⑦HTTPS移行後の混合コンテンツエラー

どんなトラブル？

サイトを常時SSL化し、URLをhttp://からhttps://へ移行しました。

しかし、ブラウザのアドレスバーに鍵マークではなく「保護されていない通信」という警告が表示されます。開発者ツールを見ると、コンソールに「Mixed Content」というエラーが出ています。

なぜ起こるの？

混合コンテンツ（Mixed Content）エラーは、HTTPSで安全に読み込まれたページ内に、安全でないHTTP経由で読み込まれるリソース（画像、スクリプト、スタイルシートなど）が混在している場合に発生します。

これは、データベースの投稿本文やカスタムフィールド、あるいはテーマファイル内に、http://から始まるURLが直接書き込まれている（ハードコードされている）ことが主な原因です。

どうすれば解決できる？

原因となっているHTTPリソースを特定し、すべてHTTPS経由で読み込むように修正する必要があります。

解決策1：原因の特定（ブラウザ開発者ツール）

まず、ブラウザの「開発者ツール」を使って、どのリソースが問題を引き起こしているのかを特定します。

  • 問題のページで右クリックし、「検証」を選択して開発者ツールを開きます。
  • 「コンソール（Console）」タブに表示される「Mixed Content」エラーを確認します。エラーメッセージには、問題となっているリソースの具体的なURLが記載されています。

解決策2：プラグインによる自動修正

「Really Simple SSL」のようなプラグインは、ページのHTMLが出力される際にhttp://のURLを動的にhttps://に書き換えることで、多くの混合コンテンツエラーを自動的に修正してくれます。

解決策3：データベース内のURLを一括置換（WP-CLI）

最も確実な方法は、データベース内に残っているhttp://のURLをhttps://に置換することです。これには、WP-CLIのsearch-replaceコマンドが最適です。このコマンドは、シリアライズされたデータを壊すことなく安全にURLを置換できます。

WP-CLIコマンドの実行例：

Bash

# まずは --dry-run で影響範囲を確認
wp search-replace 'http://example.com' 'https://example.com' --all-tables --dry-run

# 問題がなければ、実際に置換を実行
wp search-replace 'http://example.com' 'https://example.com' --all-tables

解決策4：テーマ・プラグインファイルの確認

データベースを修正してもエラーが解消しない場合、URLがテーマやプラグインのファイル内に直接書き込まれている可能性があります。特定したファイルを直接修正します。

このエラーは、開発時にhome_url()のようなWordPress関数を使って動的にURLを生成する習慣の重要性を示しています。

また、移行作業ではWP-CLIのような自動化ツールを使い、手作業によるミスを防ぐことが大切です。

⑧自作コードのセキュリティ脆弱性

どんなトラブル？

サイト内検索の結果ページで、ユーザーが入力した検索キーワードを「”” の検索結果」のようにそのまま表示する機能を追加しました。

しかし、悪意のあるユーザーが検索ボックスに<script>alert('XSS');</script>のようなJavaScriptコードを入力すると、そのスクリプトがページ上で実行されてしまう、クロスサイトスクリプティング（XSS）の脆弱性が生まれてしまいました。

なぜ起こるの？

この脆弱性の原因は、「ユーザーからの入力を決して信用しない」というセキュリティの基本原則を破ったことにあります。

$_GETや$_POSTなど、ユーザーが操作可能なデータは、悪意のあるコードを含んでいる可能性があります。

これらのデータを適切な処理なしに出力すると、XSSやSQLインジェクションといった攻撃の標的となります。

どうすれば解決できる？

WordPressにおけるセキュリティの基本は、「入力時に検証・サニタイズし、出力時にエスケープする」です。

入力時の処理：検証（Validation）とサニタイズ（Sanitization）

ユーザーから送信されたデータをデータベースに保存する前に行う処理です。

  • 検証
    データが期待される形式かを確認します（例：is_email()）。
  • サニタイズ
    データから潜在的に危険なコードを取り除き、無害化します。
    WordPressにはsanitize_text_field()（プレーンテキスト用）やwp_kses_post()（HTMLを許可しつつ危険なタグは除去）など、多くのサニタイズ用関数が用意されています。

$_POSTデータをサニタイズするコード例：

PHP

if ( isset( $_POST['user_name'] ) ) {
    $safe_user_name = sanitize_text_field( $_POST['user_name'] );
    update_user_meta( get_current_user_id(), 'user_name', $safe_user_name );
}

出力時の処理：エスケープ（Escaping）

データベースなどから取得したデータをブラウザに出力する直前に行う処理です。

データ内の文字を、HTMLなどのコンテキストで特別な意味を持たないように変換し、コードとして実行されるのを防ぎます。

エスケープ関数の使い分け：

  • esc_html(): HTMLの要素内にテキストを出力する場合。
    シナリオの解決策： <h2>"<?php echo esc_html( get_search_query( false ) );?>" の検索結果</h2>
  • esc_attr(): HTMLタグの属性内に出力する場合。
  • esc_url(): hrefやsrc属性にURLを出力する場合。

データベースクエリのセキュリティ

カスタムSQLクエリでは、SQLインジェクション対策として$wpdb->prepare()を必ず使用します。これにより、変数を安全にクエリに組み込めます。

データのサニタイズとエスケープを適切に使い分けることは、プロの開発者として不可欠なスキルです。

⑨データベース移行の失敗とシリアライズデータ

どんなトラブル？

開発環境から本番環境へサイトを移行するため、データベースをエクスポートし、テキストエディタの「すべて置換」機能でURLを一括変換してインポートしました。

しかし、サイトを表示するとレイアウトが崩れ、ウィジェットやテーマオプションが初期化されています。

なぜ起こるの？

この原因は、WordPressがウィジェット設定などを「シリアライズ化されたPHPデータ」としてデータベースに保存しているためです。

シリアライズとは、PHPの配列などをデータベースに保存可能な文字列に変換することです。この文字列には、データそのものだけでなく、文字列の長さといった構造情報も含まれています。

シリアライズされたデータの例：

s:19:”http://dev.local”;

このs:19は、続く文字列が19文字であることを示しています。これを単純なテキスト置換で　https://production.site（22文字）に置き換えると、文字数と構造情報が一致しなくなり、データが破損したとみなされます。その結果、設定が読み込めなくなってしまうのです。

どうすれば解決できる？

この問題を回避し、安全にデータベースを移行するための標準ツールがWP-CLI（WordPress Command Line Interface）です。

解決策：wp search-replaceコマンド

WP-CLIのsearch-replaceコマンドは、シリアライズを認識するように設計されています。

URLを置換する際に、文字列の長さを自動的に再計算し、データの構造を維持したまま安全に書き換えてくれます。

データベース移行のベストプラクティス・ワークフロー

  • 事前確認 (–dry-run)
    データベースに実際に変更を加える前に、必ず–dry-runフラグを付けてコマンドを実行します。これにより、どのテーブルで何件の置換が行われるかを確認できます。
    Bash
    wp search-replace 'http://dev.local' 'https://production.site' --dry-run
  • GUIDカラムの除外 (–skip-columns=guid)
    wp_postsテーブルのguidカラムは、投稿をRSSリーダーなどで一意に識別するためのもので、ドメインが変わっても変更してはいけません。--skip-columns=guidフラグで、このカラムを置換対象から除外します。
  • コマンドの実行
    事前確認後、問題がなければフラグを外して本番のコマンドを実行します。

    ベストプラクティスに則った最終的なコマンド例
    Bash
    wp search-replace 'http://dev.local' 'https://production.site' --skip-columns=guid --all-tables

このトラブルは、WordPressのデータの裏側にある構造を理解し、適切なツールを使って作業することの重要性を示しています。

⑩WordPressマルチサイト特有の課題

どんなトラブル？

クライアントの複数サイトを効率的に管理するため、WordPressのマルチサイト機能を導入しました。

しかし、あるサイトで有効化したプラグインが別のサイトの表示を崩したり、各サイトの管理者がプラグインを自由にインストールできなかったり、独自ドメインを割り当てると管理画面にログインできなくなったりと、問題が続出します。

なぜ起こるの？

マルチサイトの強力な特徴であるリソースの共有（単一のWordPressコア、共有のテーマ・プラグイン、共有のユーザーデータベース）が、同時にその複雑さの原因でもあります。

  • プラグインの競合
    マルチサイトに対応していないプラグインは、ネットワーク全体に意図しない影響を及ぼすことがあります。
  • ユーザー権限の複雑さ
    プラグインやテーマのインストールは「ネットワーク管理者（Super Admin）」しか行えず、各サイトの「サイト管理者」は有効化／無効化しかできません。この階層構造が混乱を招きます。
  • ドメインマッピングとクッキーの問題
    各サイトに独自ドメインを割り当てた際にログインループに陥る問題は、WordPressが発行する認証クッキーが、ネットワークのプライマリドメインに対して設定されてしまうために発生します。

どうすれば解決できる？

マルチサイトを安定して運用するには、その特有の仕組みを理解し、適切な管理を行う必要があります。

プラグイン競合のトラブルシューティング

  • 互換性の確認
    プラグインを導入する際は、公式に「マルチサイト互換」とされているかを確認することが重要です。
  • 体系的なデバッグ
    問題が発生した場合、すべてのプラグインを無効化し、一つずつ有効化しながら動作確認を行う、という地道な切り分け作業が最も確実です。

ユーザー権限の管理

サイト管理者がプラグインを自由にインストールできないのは、ネットワーク全体のセキュリティと安定性を保つための仕様です。

プラグイン導入のリクエストをどのように処理するかの運用ルールを明確に定めておくことが重要です。

ドメインマッピング時のクッキー問題を解決する

独自ドメインでのログインループ問題は、wp-config.phpにいくつかの定数を定義することで解決できます。

これにより、各サイトが自身のドメインに対して正しくクッキーを発行できるようになります。

wp-config.phpに追加するコード例

PHP

/* That's all, stop editing! Happy publishing. */ の直前に追加

define('ADMIN_COOKIE_PATH', '/');
define('COOKIE_DOMAIN', '');
define('COOKIEPATH', '');
define('SITECOOKIEPATH', '');

特にdefine('COOKIE_DOMAIN', '');と設定することで、WordPressはクッキーのドメインを固定せず、アクセスされた各サイトのドメインに動的に合わせるようになります。

マルチサイトの管理は、単一のサイト構築とは異なり、システム全体を管理する視点が求められます。

共有リソースやネットワークレベルの設定を理解することが、安定運用の鍵となります。

結論：パターンを理解し、エキスパートへ

この記事で解説した10の技術的トラブルは、中級レベルのWordPress開発者が直面する現実的な課題です。

これらの問題には共通のテーマがあります。それは、「ただ動く」コードから、「効率的に、安全に、そして拡張性を持って動く」コードへの移行です。

駆け出しの頃に身につけたスキルは、機能を「作る」ためのものでした。しかし、エキスパートへと成長するためには、その機能がシステム全体に与える影響を予測し、制御する能力が求められます。

  • パフォーマンスは、後付けではなく設計段階から考慮すべき品質であること。
  • セキュリティは、開発者自身がデータの入出力すべてに責任を持つべき基本原則であること。
  • メンテナンス性は、コードのロジックだけでなく、その構造と配置によって決まること。
  • 安定性は、WordPressの内部メカニズムを理解し、再現性の高いプロセスを構築することで得られること。

これらのトラブルを一つ一つ解決していく過程は、問題の背後にある普遍的な「パターン」を見抜き、体系的なアプローチで対処する訓練になります。

この能力こそが、中級者から上級者へとステップアップするための鍵となるのです。

この記事が、あなたが直面している課題を乗り越え、より信頼されるWordPress開発者へと成長するための一助となれば幸いです。

コナン先生のWebトラブル何でも相談窓口

Webサイトに関するあらゆる「困った」に対応します。ぜひ一度ご相談ください。

コナン先生のWebトラブル何でも相談窓口