WordPress テーマを更新すると設定が消える？
テーマの再アップロードで写真・ロゴが初期化される「カスタマイズ設定リセット」問題。受託案件で実際に直した原因と恒久対策を共有します。
🗂️ 3行でわかるポイント
- 1テーマ更新のたびに写真・ロゴ等のカスタマイザー設定がデフォルトに戻る
- 2原因は theme_mods が theme_mods_{テーマフォルダ名} で保存されること
- 3固定フォルダ名運用 + 移行関数の堅牢化で恒久解決（wp-env で E2E 検証）
キーワード
この記事でわかること
- ✓更新で設定が消える本当の原因
- ✓固定フォルダ名運用という恒久対策
- ✓フォルダ名が変わっても引き継ぐ移行関数
- ✓wp-env による実機 E2E 検証
「テーマを更新したら、設定していた写真が古いものに戻ってしまった」—— WordPress テーマの受託・保守でときどき遭遇する、地味だが厄介な事象です。
カスタマイザーで設定したロゴ・トップ画像・色・電話番号などが、テーマの再アップロードを境に 一斉にデフォルト（テーマ同梱の初期画像）へ戻る。再設定してもまた次の更新で消える——。 原因が分かりにくく、「WordPress の不具合」と誤解されがちですが、 実際は theme_mods の保存のしくみに起因する、再現性のある問題です。
🔍原因 — 設定キーがフォルダ名に紐づく
カスタマイザーの設定値（get_theme_mod() / set_theme_mod()）は、 WordPress の options テーブルに theme_mods_{テーマフォルダ名} というキーで保存されます。写真・ロゴ・色などは、ほぼこの theme_mods に入っています。
ここで、テーマを my-theme-1.5.0 → my-theme-1.5.1 のようにバージョン付きフォルダ名でデプロイすると、 保存キーが theme_mods_my-theme-1.5.0 → theme_mods_my-theme-1.5.1 と別物になり、 新フォルダ側には設定が無い＝デフォルト表示に戻ってしまうのです。
theme_mods の保存先
theme_mods_{stylesheet} という options 行に格納。stylesheet = テーマのフォルダ名 なので、フォルダ名が変わると別キー扱いになります。
バージョン付きフォルダの罠
デプロイ毎にフォルダ名へバージョンを付けると、更新のたびにキーが変わり、 カスタマイザー設定がリセットされます。
🛠️恒久対策 — 2 段構え
① フォルダ名を固定する（本命）
テーマフォルダ名を バージョン非依存の固定名 にし、更新は同じフォルダを上書きする運用に。 バージョンは style.css の Version: と git タグで管理します。 これでキーが永遠に一定になり、リセットが原理的に発生しません。
② 移行関数（安全網）
それでもフォルダ名が変わってしまった場合に備え、after_switch_theme で WordPress が渡す 「直前にアクティブだったテーマ」($old_theme) から theme_mods を確実にコピー。フォールバックは version_compare で「設定が入っている最新バージョン」を選びます。
ポイントは安全網の移行元の選び方です。 素朴に「最初に見つかった theme_mods をコピー」すると、古いバージョンの設定を復元してしまう（＝古い写真に戻る） 事故が起きます。WordPress が教えてくれる「直前のテーマ」を使い、 無ければ version_compare で最新の非空エントリを選ぶ——これで取り違えを防げます。
🧪検証 — wp-env で実テーマ切替 E2E
「設定が消えない」は実機で確かめないと意味がありません。@wordpress/env 上で実際にテーマフォルダを複製・有効化し、 3 シナリオで移行関数を検証しました。
移行
固定フォルダへ有効化 → 直前テーマから設定を引き継ぐ。
フォールバック
直前が空でも、設定が入っている最新バージョンを選択（古い版を選ばない）。
再デプロイ保持
同じ固定フォルダを上書きしても設定が保持される。
💡教訓
- フォルダ名にバージョンを含めない。 バージョンは style.css と git タグで管理する。
- 「定義済」と「上書き不要」は別概念。 キーがフォルダ名に紐づく以上、フォルダが変われば設定は別物になる。
- 安全網の移行元は決定的に選ぶ。 「最初に見つかった値」ではなく、直前テーマ or 最新バージョンを選ぶ。
- 実機で検証する。 wp-env で実際にテーマ切替を再現し、設定が残ることを確認する。
i-Willink では WordPress 受託・保守でこうした「運用で詰まる落とし穴」を構造から潰し、 お客様が安心して更新できる状態を維持しています。