WordPress納品後によく起こる「カスタムフィールドの値が反映されない」問題の解決法｜現場で使える実践テクニック

こんにちは！

今日は「WordPress納品後によく起こるカスタムフィールドの値が反映されない問題」について解説します。

納品後によく聞く「あ、カスタムフィールドの値が出てない…」

僕も経験してるんですけど、納品から1週間くらい経って、クライアントから「あ、このページのここの部分、テキストが表示されてないんですけど」という連絡をもらうことってめっちゃありますよね。
そして確認してみると、カスタムフィールドの値が画面に反映されていない、という状況です。

こういう時、パニックになる必要はありません。
ほんまに大概の場合は、テンプレートファイルの書き方が原因なんです。
環境が違うとか、プラグインの衝突とか、ほかの要因もありますけど、まずは基本を抑えておくといいですよ。

納品後のサポート期間中に修正する場合もあれば、クライアント側で更新中に自分たちで触ってしまって壊れた、というパターンもあります。
どちらにしても「なぜ出ないのか」を論理的に診断できると、対応がスムーズになるんです。

原因の9割はthe_field()とget_field()の使い分け

Advanced Custom Fields（ACF）プラグインを使ってる案件が多いと思うんですけど、ここでよくある勘違いが「the_field()とget_field()の違い」です。

まず、この2つの関数の違いを整理しておきます。
the_field()は値を直接出力（echo）します。
get_field()は値を取得して返します。

つまりこんな感じです：

the_field('field_name')を使った場合は、テンプレートに直接書くだけで画面に表示されます。
でもget_field('field_name')で取得した場合は、その値を変数に入れて、その後にechoなり何なりで出力する必要があるんです。

僕が見かけるのは、こういうケースです。
テンプレートでget_field('field_name')だけ書いてあって、その値を出力していない。
つまり、値は取得できてるのに、画面には何も表示されてない、という状況ですね。

もう1つよくあるのが、ループの中でカスタムフィールドを使う時の落とし穴です。
複数の投稿が並んでるアーカイブページで、各投稿のカスタムフィールドを表示する場合、the_field()を使う時は投稿IDを明示的に指定しないといけません。
the_field('field_name', $post_id)という感じで、第2引数にIDを渡さないと、現在のグローバルな投稿IDを参照するので、うっかり別の投稿の値が表示されることもあります。

ACFプラグイン自体の問題を切り分ける方法

テンプレートの書き方は正しいのに、それでも値が出ない場合もあります。
その時は、ACFプラグイン側の問題を疑う必要があります。

まず確認することは、WordPress管理画面のカスタムフィールド設定が、本番環境にちゃんと反映されてるかです。
ACFのフィールド定義は、wp-content/plugins/advanced-custom-fields-pro内に保存されるんですけど、開発環境で作ったフィールド定義が本番に移行されてない、ということがあります。

僕が以前やった失敗談なんですけど、開発環境でフィールド定義を作って、テンプレートを作って、納品前に動作確認もしたんです。
でも本番環境にプラグインの設定だけ引き継いでなくて、フィールド定義がなかった、という状況がありました。
だからクライアントがデータを入力しても、画面に表示されなかったんですよ。

確認する方法としては、WordPress管理画面の「Custom Fields」メニュー（またはACFの設定画面）から、該当するフィールドグループが存在してるか、そしてその中に期待するフィールドが含まれているかを見るといいですよ。
もしフィールド定義がないなら、ACFのデータベースバックアップから復元するか、あるいは手動で再度作り直す必要があります。

もう1つ確認すべきは、投稿タイプ（Post Type）とカスタムフィールドの関連付けです。
ACFでフィールドグループを作る時、「どの投稿タイプに適用するか」を設定しますよね。
もし「Pages」にしか適用されてないのに、カスタム投稿タイプに同じフィールドを使おうとしたら、当然値は出ません。

納品チェックリストに追加すべき確認項目

こういったトラブルを防ぐために、納品前に必ずチェックしておくといいポイントがあります。

1つは「本番環境で実際にカスタムフィールドにデータを入力して、フロントエンドに表示されるか」を確認することです。
開発環境では見えてたけど、本番では見えない、という状況を事前に防げます。

2つ目は「複数の異なる投稿でテストする」ことです。
1つの投稿だけ動作確認するのではなく、複数投稿で試して、ループ処理の中でもちゃんと動作してるか確認するといいですよ。

3つ目は「プラグインの有効化状態を確認する」ことです。
デプロイ後、ACFプラグインが本番環境で有効化されてるか、バージョンは合ってるか、確認するようにします。
開発環境がACF PRO（有料版）で、本番がACF Free（無料版）だと、機能の差で動かないこともあります。

4つ目は「操作マニュアルにカスタムフィールドの入力例を含める」ことです。
クライアントが「どのフィールドに何を入力すればいいのか」分からなかったら、結果的に値が入ってないことになります。
スクリーンショット付きで丁寧に説明するといいですよ。

まとめ

カスタムフィールドの値が反映されない問題は、ほとんどの場合「テンプレートの書き方」か「ACFの設定」に原因があります。
the_field()とget_field()の違いを理解して、ループの中では投稿IDを明示的に指定する。
そして本番環境でしっかりテストする。
この3つをおさえておくと、納品後のトラブルはかなり減ると思いますよ。

最初は「なんで出ないんだ…」ってパニックになるかもしれません。
でも原因を切り分け