Cocoonでサムネイルがぼやけた｜以前あったRetina設定が見つからなかった話と、子テーマで直した記録

2026年1月2日の夜、自宅のデスクで、ようやくRapls PDF Image Creatorの初回SVNリリースを終えて、ターミナルを閉じたところでした。WordPress.orgへの公開という、半年がかりの作業がやっと一段落して、肩の力がふっと抜けた瞬間です。

そのまま、開いたままだったMacBookで、なんとなく自分のブログ「Rapls Works」のトップページを開いてみました。

「……あれ?」

記事一覧に並んだサムネイル画像が、軒並みぼんやりして見えていました。1枚や2枚ではありません。トップページに並んでいるアイキャッチ、ほぼ全部です。

本文の中の画像は普通に見えるのに、トップページのカード型サムネイルだけが、なんだか少し甘い。スクリーンショットの細い線がにじむような感じで、文字も角がぼやけて読みにくい。

手元のiPhone 17でも開いてみたら、やはり同じように眠たく見えました。複数のデバイスで同じ症状が出ているということは、自分の目の問題でも、画面の調子でもなく、配信されている画像そのものに何かある、と察しがつきます。

検証環境：WordPress 6.9 / Cocoon 2.8.9 / Xserver スタンダードプラン / PHP 8.3.21 / 確認デバイスは Intel MacBook Pro 16inch(2019モデル)と iPhone 17 / WP-Rocket と Compress X(Avif) を併用 / 検証は2026年1月、本記事の最終確認は2026年5月。

まずは元画像を疑った、けれども問題なかった

サムネイルがぼやけて見える、と気づいたとき、最初に頭に浮かんだのは「アップロードした元画像のサイズが小さかったんじゃないか」でした。アイキャッチに使っているのは、たいていプラグインの管理画面のスクリーンショットや、自作した解説図です。元画像が小さければ、当然サムネイルもきれいには出ません。

メディアライブラリを開いて、いくつかの記事のアイキャッチを順番にクリックして、元画像のサイズを確認していきました。「画像の編集」画面で右側に表示される情報欄から、ピクセル数が見られます。

結果、元画像のサイズは1280pxや1920pxを超えるものがほとんどで、明らかに「足りない」と言えるものはありませんでした。十分な解像度がある画像をアップロードしているのに、サムネイルだけがぼやける。じゃあなんで?

キャッシュも疑った、これも空振り

次に思いついたのは、ブラウザキャッシュとサーバーキャッシュです。サイトでWP-Rocketを使っているので、キャッシュが古い画像を表示しているという可能性は十分あります。

WP-Rocketの管理画面から全キャッシュを削除して、ブラウザもCmd+Shift+Rでハードリロード。それでもサムネイルはぼやけたままです。シークレットウィンドウで開いてみたり、別のブラウザで確認してみたりもしましたが、症状は変わりません。

キャッシュ系の問題ではないと、ここで切り分けが進みました。

開発者ツールで実物のURLを見てみる

こうなったら、画面に実際に表示されている画像が「物理的に何ピクセルなのか」を直接確認するしかありません。Chromeでトップページを開いた状態で、Cmd + Option + I を押して開発者ツールを開きました。

左上の矢印アイコンをクリックして、トップページに並んでいるサムネイルのひとつを指定します。

選択された<img>タグのsrc属性を見たとき、ちょっと「あー」と声が出ました。URLの末尾が、こんな形になっていたのです。

ファイル名にしっかり -320x180 と入っています。表示領域とちょうど同じピクセル数の画像が読み込まれている、ということです。

サムネイル画像が画面で表示されている見た目のサイズは、たしかに320×180px相当でした。けれど、私が使っているMacBook Pro 16inchもiPhone 17も、画面が高解像度ディスプレイです。同じ「320×180px」と言っても、物理的なピクセルは2倍以上を使って描画されています。

ここで、ようやくぼんやり原因が見えてきました。

そもそも、Retinaディスプレイってどういう仕組みなんだっけ

MacBookやiPhoneの画面は、物理的な解像度がとても高くなっています。たとえば見た目のサイズは320pxでも、内部では640px以上の細かさで描画していることがあります。

320×180pxの表示領域に対して、本当に320×180pxの画像を渡してしまうと、Retinaディスプレイは「足りないぶん、引き伸ばして表示」することになります。引き伸ばされた画像は、当然ながら輪郭が甘くなる。これが、私が「眠たい」と感じていた表示の正体です。

解決策として用意するべきなのは、表示領域より大きめのサムネイル画像です。320×180pxの場所には、640×360pxの画像を読み込ませる。これなら高解像度ディスプレイでも、ピクセルが足りない状態にはなりません。

Cocoonには昔、Retina対応のチェックボックスがあったはず

「あ、これってCocoonに専用設定があったんじゃないかな」と、ここで思い出しました。

Cocoonは多機能な国産テーマで、画像まわりの設定もかなり細かく揃っています。「Cocoon設定 → 画像」の中に、Retinaディスプレイ向けのサムネイル生成をオンにする項目があったはず、という記憶がありました。

念のため、執筆前に他のCocoon Retina対応の解説記事もいくつか読んでみました。多くの記事で同じ手順が紹介されています。Cocoon公式マニュアルにも、しっかり書いてありました。

「画像」タブにある「全体画像設定」項目中の「Retinaディスプレイ」の設定を変更します。

「よし、これだな」と思って、WordPress管理画面に入って、Cocoon設定を開きました。

あれ、Retinaの項目が見当たらない

Cocoon設定 → 画像タブ → 全体画像設定。手順としては、ここに目当てのチェックボックスがあるはず、でした。

ところが、画面の中を上から下までスクロールしても、Retinaに関連する項目がどこにも見当たりません。

「あれ……?」

もしかして自分が見落としているのかもしれない、と何度かページを行き来して、設定項目を順番に確認していきました。「全体画像設定」のブロックも一つひとつ見ましたが、サムネイルサイズに関する項目はあっても、Retinaそのもののスイッチはやはりありません。

画像タブ以外も見たほうがいいかもしれない、と思って、「投稿」「インデックス」「アピールエリア」などのタブも順番に開いてみましたが、状況は変わりませんでした。

「うーん、どこかで仕様が変わったのかな」

Cocoonは結構頻繁にアップデートされていて、機能の整理や追加が定期的に行われています。私の環境はCocoon 2.8.9でした。公式マニュアルの記述が、最新版のテーマ仕様に追いついていない、という可能性は十分あります。

ソースコードを直接覗くことにした

管理画面に項目がない、けれど他の解説記事と公式マニュアルにはある、と書いてある。となると、確認できる場所はテーマの中身しかありません。

普段、私は仕事でもブログ用のカスタマイズでも、テーマやプラグインのソースコードをBBEditのMulti-file searchで横断検索する、というやり方をよくします。今回もこの方法で、Cocoon親テーマのフォルダ全体に対して、検索キーワード「retina」で探してみました。

ヒットしたのは、4つのファイルです。

• about-forms.php
• image-forms.php
• image-funcs.php
• image-posts.php

それぞれのファイルを開いて、検索結果の前後の文脈を読んでみると、設定値の名前が retina_thumbnail_enable であることが見えてきます。Retinaサムネイルを有効化するためのフラグそのものは、テーマファイルの中にしっかり残っていました。

機能の中身は生きていて、管理画面のチェックボックスだけが外された状態のようです。

ソースを読み解く過程では、Cursor上のClaude Codeにも「このファイルでretina_thumbnail_enableがどう使われているか教えて」と尋ねながら進めました。AIに概要を整理してもらうと、コードの分量が多くても流れがつかみやすくなります。これは普段のプラグイン開発でもよく使う組み合わせです。

Cocoonのアップデート履歴を一行ずつ追って確認したわけではないので断定はできないのですが、過去のどこかのバージョンで、管理画面側の項目が整理された(たぶん他の設定の整理整頓に合わせて)タイミングがあったのではないかと推測しています。機能のフラグは残しつつ、UIだけ削った、という感じです。

幸いなことに、内部のフラグが残っているということは、子テーマのfunctions.phpからフィルターでこの値を強制的に書き換えれば、Retinaサムネイルを有効化できます。実際、この方法できれいに動きました。

子テーマのfunctions.phpを開く前に、いったん深呼吸

Retinaサムネイルを復活させる方針が決まったので、ここからは実装作業です。

その前に、これは何度言っても言い足りないのですが、functions.phpの編集はバックアップを取ってから手をつけるようにしてください。短いコードを追加するだけでも、書き間違えるとサイトが真っ白になることがあります。私自身、過去に何度か白画面を見ているので、今でも編集前のバックアップは習慣にしています。

あわせて、子テーマが有効化されていることも確認してください。Cocoonの場合、親テーマが「Cocoon」で、子テーマが「Cocoon Child」という名前で配布されています。「外観 → テーマ」を開いて、有効になっているのが「Cocoon Child」のほうであることをチェックします。

もし子テーマがまだ入っていない場合は、Cocoon公式サイトから子テーマzipをダウンロードして、先にインストールしておきます。親テーマを直接編集してしまうと、Cocoonがアップデートされたタイミングで全部消えるので、ここは妥協しないでおきたいところです。

functions.phpに3行だけ書き足す

WordPress管理画面の「外観 → テーマファイルエディター」を開きます。

右側のファイル一覧から、子テーマ側のfunctions.phpを選びます。ファイル名は同じでも、親テーマのものと子テーマのものが両方存在するので、間違わないように。画面右上のセレクトボックスで「編集するテーマを選択」が「Cocoon Child」になっているかを確認します。

ファイルの末尾に、これだけのコードを追加します。

3行だけです。add_filterはWordPress標準の仕組みで、テーマやプラグイン側の設定値を、外から書き換えるためのフックです。theme_mod_retina_thumbnail_enableはCocoonがRetina対応を判定するために読んでいる設定キーで、この値を1(有効)に強制しているだけ、というシンプルな構造です。

子テーマのfunctions.phpが初期状態に近い場合、全体としてはこんな形に落ち着きます。

すでにfunctions.phpに別のコードを書いている場合は、既存のコードはそのままにして、末尾に追加すれば大丈夫です。

書けたら、画面下の「ファイルを更新」ボタンをクリックします。

「ファイルの編集に成功しました。」というメッセージが出れば、保存はOKです。

もし保存後にサイトを見て真っ白だったり、エラー表示が出ていたりしたら、いったん落ち着いて、追加したコードのカッコや「;」の閉じ忘れがないかを確認してください。バックアップから戻すのも有効です。

ここまでで、これからアップロードする画像については、Retina向けのサムネイルが自動で生成されるようになります。ただし、過去にアップロード済みの画像のサムネイルは、まだ古いままです。

ここからは過去の画像も作り直す

WordPressは、画像をアップロードしたタイミングでサムネイルを生成します。functions.phpにコードを追加しただけでは、過去にアップロードした画像のサムネイルが自動で作り直されることはありません。

過去の記事一覧やトップページのサムネイルもきれいにしたい(私はこれが目的でした)場合は、サムネイルを再生成する作業が必要になります。これにはRegenerate Thumbnailsという定番プラグインを使います。

「プラグイン → 新規追加」を開いて、検索欄に「Regenerate Thumbnails」と入力します。

表示されたプラグインをインストールして、有効化します。

「ツール → Regenerate Thumbnails」のメニューを開きます。

画面に出てくる「Regenerate Thumbnails For All Attachments」ボタンを押すと、メディアライブラリ内のすべての画像について、サムネイルが作り直されます。

処理が始まると、画面にプログレスバーが表示されます。途中でブラウザのタブを閉じたり、別のページに移動したりしないようにします。

私の環境では、その時点でブログにアップロードしていた画像が、たぶん30枚くらいでした。Regenerate Thumbnailsでの再生成は、Xserver スタンダードプランで数分ほどで終わって、途中でブラウザがフリーズすることもなく、サーバーが重くなる感じもありませんでした。

これが数百枚〜数千枚の画像があるサイトだと、また別の話だと思います。サーバーの負荷が気になる場合は、夜間など、サイト訪問の少ない時間帯にやっておくのが無難です。

もしRegenerate Thumbnailsで反映されない画像がある場合は、既存のサムネイルファイルを削除してから作り直すタイプの再生成プラグインに切り替える方法もあります。ただ、削除を伴う処理は影響が大きいので、サーバー側で確実にバックアップを取ってからのほうが安心です。

本当に2倍サイズになっているかを確認する

再生成が終わったら、最初に開発者ツールで見たのと同じ場所を、もう一度確認します。

トップページを開いて、Cmd + Option + I で開発者ツール。さっきと同じ手順で、サムネイル画像のsrc属性を見てみます。

URLに含まれているサイズ表記が、640×360のように2倍の数字に変わっていれば、Retina向けのサムネイルが新しく生成されている、ということになります。

あとは、実機でも見え方を確認します。MacBookやiPhoneで自分のブログのトップページを開いて、サムネイルがくっきりしていれば、想定通りの動作です。

私は、これで一気に印象が変わりました。本文の内容は同じでも、トップページがしっかりして見える。なんというか、サイトとして最低限の手入れができている感じが、すこし戻ってきたような気がしました。

ファイルサイズはどれくらい増えた? PageSpeedはどうなった?

サムネイルが2倍サイズになると、当然ファイルサイズも増えます。表示領域320×180px向けのサムネイルで考えると、対応前は20〜30KB前後だったファイルが、対応後の640×360pxでは60〜100KB程度になることもあります。1枚あたりの差は小さくても、サイト全体の画像枚数が多ければ、合計ではそれなりに変わります。

PageSpeed Insightsでスコアがどうなるか、気にしながら見ました。

結果としては、Retina対応の前後で、モバイルスコアは96点のまま、まったく動きませんでした。これは、私のサイトの構成が幸運だったのかもしれません。

Rapls Worksでは、ページ表示の高速化にWP-Rocketを使い、画像の配信にはCompress XというAvif変換プラグインを併用しています。Avifは、同じ見た目の画像でもPNGやJPEGよりファイルサイズが小さくなる新しいフォーマットです。サムネイルのピクセル数が2倍になっても、配信されるAvifのファイルサイズはそこまで増えていない、という可能性があります。

あくまで推測なので、ご自身のサイトでスコアの動きを確認するのが一番確実です。画像をきれいにしつつ、ページの軽さも保つには、配信側のチューニング(キャッシュ、画像フォーマット最適化)も合わせて見ておく価値があると思います。

気をつけたいこと、いくつか

Retina対応をかけると、画像はきれいになりますが、いくつか頭の片隅に置いておきたいことがあります。

一つは、元画像のサイズです。640×360pxのサムネイルを作るには、元画像が最低でも640×360px以上必要です。それより小さい元画像をアップロードしている場合、Retinaサイズのサムネイルは作れません。アイキャッチを用意するときは、できるだけ大きめの画像を選んでおくと、後から困らないです。

もう一つは、サーバーのストレージ容量です。サムネイルの数が増えるぶん、メディアライブラリ全体の容量も増えます。私の環境では正確な測定はしなかったのですが、サイト規模が大きい人ほど、再生成前後でストレージの使用量を一度確認しておくと安心です。

それから、再生成中のサーバー負荷。30枚程度なら一瞬で終わりましたが、画像が数百枚を超えるサイトだと、再生成中にサーバーレスポンスが落ちる可能性があります。同じ時間帯にサイト訪問が集中していると、訪問者にとっては「重いサイト」になってしまうので、夜間帯にやるのが無難です。

よく聞かれる質問

Cocoon設定の中にRetinaの項目が見当たらないのですが、これで合っていますか?

合っています。私が確認したCocoon 2.8.9では、「Cocoon設定 → 画像」の中にRetinaディスプレイ用の項目が見当たりませんでした。Cocoon公式マニュアルにはその手順が書かれていますが、現行のテーマでは管理画面側の設定項目が見つからない状態のようです。

機能の中身そのものはテーマ内に残っているので、子テーマのfunctions.phpからフィルター経由で値を渡してあげれば、同じ効果が得られます。

子テーマなしでもできますか?

技術的には親テーマを直接編集しても同じことができますが、おすすめしません。Cocoonがアップデートされたタイミングで、編集した内容が全部消えるからです。

「アップデートを当てた瞬間にぼやけ問題が再発した、何が起きたんだろう」と原因を探すのは、けっこう疲れます。最初から子テーマで対応しておいたほうが、長期的にラクです。

既存の記事のサムネイルも変わりますか?

functions.phpにコードを追加しただけでは、既存画像のサムネイルは変わりません。Regenerate Thumbnailsなどでサムネイルを再生成する作業が、別途必要です。

元画像が小さい場合もきれいになりますか?

元画像が小さい場合は、効果が出にくいです。640×360pxのサムネイルを作りたいのに元画像が320×180pxしかない、というケースだと、Retinaサイズのサムネイルは生成されません。アイキャッチには、できるだけ大きめの画像(目安としては最低1280×720px、推奨1920×1080px以上)を用意しておくと安心です。

新しくアップロードする画像にも反映されますか?

はい。コードを追加した後にアップロードする画像については、自動的にRetina向けのサムネイルが生成されます。再生成は不要です。

ただし、元画像のサイズが小さいと、期待したサイズのサムネイルが作られないことがあるので、そこだけ注意です。

元に戻したい場合はどうすればいいですか?

functions.phpに追加したコードを削除すれば、今後生成されるサムネイルは元の設定(Retina非対応)に戻ります。すでに生成済みのRetinaサムネイルも戻したい場合は、コード削除後にもう一度Regenerate Thumbnailsで再生成してください。

こちらも、作業前にバックアップを取っておくと安心です。

使ってから問題が起きていませんか?

子テーマで対応してから数ヶ月、サムネイルまわりで特に問題は起きていません。新しい記事をアップロードしても、自動的にRetina用の2倍サイズのサムネイルが生成されています。Cocoonのアップデートが入っても、子テーマ側のfunctions.phpは消えないので、対応が継続しています。

振り返って思うこと

普段、私はWordPress.orgに3つのプラグイン(Rapls PDF Image Creator、Thanks Mail for Stripe、Rapls AI Chatbot)を公開しているフリーランスエンジニアです。Web開発は6年以上やっていて、最近はWordPress.orgのJapanese localeでProject Translation Editor(PTE)も務めていて、他の方が出されたプラグインの翻訳承認も担当しています。

このブログ「Rapls Works」は、Cocoonをテーマに使って2025年12月25日から運営をはじめました。プラグイン開発で気づいたことや、自分のサイトをCocoonでカスタマイズしていく過程で見つけた発見を、開発の延長として書いています。

今回のRetinaサムネイルの件は、技術的には3行のコードで終わる話なのに、そこに辿り着くまでに公式マニュアルとの差異という遠回りがありました。「公式どおりに探したのに見当たらない」というのは、ユーザーとしてはけっこう焦る瞬間です。同じ場所で詰まる人がきっといるはず、と思ったので、こうして時系列で記録に残しておきました。

そして、Cocoonのソースコードを直接読んで、フックで設定値を上書きする、という解決の流れに自然に持っていけたのは、たぶん普段のプラグイン開発の習慣のおかげだと思います。困ったら一次情報を読む、という当たり前のことが、今回も役に立ちました。

MacBookやiPhoneで自分のブログを見たときに、サムネイルだけがどうもぼんやりしている、と感じたら、まずは開発者ツールでURLの中の数字を見てみるのが、いちばん早い切り分けかもしれません。-320x180みたいな表記があれば、その時点でだいたい状況が見えてくると思います。

あわせて読みたい関連記事

WordPressやCocoonまわりでつまずいた話は、別の記事にもまとめています。

• Site Kitのgsi/clientがPageSpeedスコアを19点下げていた
• PDFサムネイルの自動生成には「Rapls PDF Image Creator」が便利
• Cocoon公式サイト
• 同じ筆者のWordPress.orgプロフィール(公開プラグイン3つ)

サムネイルの表示品質は、本文に比べると地味な部分ですが、サイト全体の印象に意外と効きます。MacBookやiPhoneで自分のサイトを見て「なんか眠たいな」と感じる瞬間があったら、開発者ツールで一度サムネイルのURLを覗いてみてください。