コンテンツへスキップ
WordPress保守

WordPressのメンテナンスモード（.maintenance）の仕組み — 更新が途中で止まったとき、画面はなぜ「準備中」のままに見えるのか

プラグインやWordPress本体の更新中に、サイトを開くと「ただいまメンテナンス中です」といった英語の短い画面が出ることがある。更新が正常に終われば自然に消えるが、更新の途中でブラウザを閉じたり、通信が切れたりすると、「いつまでもこの画面のままではないか」と不安になる。

この仕組みの正体は、サイトのルートに置かれる .maintenance という小さなファイル1つである。今回は、WordPress 7.1.2 のコアソースを読みながら、このファイルが「いつ作られ」「何を見て有効と判断され」「いつ無効になるのか」を整理する。あわせて、wp maintenance-mode コマンドと、更新が止まったように見えるときの確認順序も紹介する。

補足: 本記事の確認は、このブログのサーバーでコアソースの読み取りと wp maintenance-mode status（状態表示のみ）を実行したものである。確認のために本番サイトをメンテナンス状態にすることはしていない。

メンテナンスモードの正体は「.maintenance ファイルが存在するかどうか」

WordPress には、管理画面の「メンテナンスモード」というスイッチがあるわけではない。更新の開始時にコアがルートディレクトリ（wp-config.php と同じ階層）へ .maintenance というファイルを書き込み、終了時に削除する。この2つだけで状態が決まる。

更新処理を担う WP_Upgrader クラスの maintenance_mode() メソッドを読むと、書き込まれる内容は次の1行であることが分かる。

<?php $upgrading = 1790000000; ?>

$upgrading は、そのファイルを作った時点の UNIX タイムスタンプ（1970年1月1日からの経過秒数）である。つまりこのファイルは「更新を始めた時刻の記録」であって、メンテナンス画面の文言や設定を持っているわけではない。

補足: 先頭が .（ドット）のファイルは、多くの環境で隠しファイルとして扱われる。FTP クライアントや ls では、隠しファイルを表示する設定にしないと見えないことがある。

更新の前後で maintenance_mode() が呼ばれる

コアのソースで maintenance_mode( true ) の呼び出し箇所を見ると、プラグインの更新・テーマの更新・自動更新（バックグラウンド更新）の各処理で、更新の直前に有効化し、完了後に無効化する構造になっている。

  • プラグインの更新（class-plugin-upgrader.php）
  • テーマの更新（class-theme-upgrader.php）
  • 自動更新（class-wp-automatic-updater.php）

有効化の際は、既存のファイルがあればいったん削除してから、新しいタイムスタンプで書き直す。無効化の際は、ファイルが存在すれば削除する。処理が最後まで走れば、必ず削除まで到達するというのが正常系である。

リクエストが来るたびに、コアは .maintenance を確認している

では、訪問者がページを開いたとき、何が起きるのか。WordPress は起動の早い段階（wp-settings.php の中）で wp_maintenance() を呼ぶ。その中身を要約すると、次の流れになる。

  1. wp_is_maintenance_mode() で、メンテナンス中かどうかを判定する
  2. 該当しなければ、そのまま通常の処理を続ける
  3. 該当する場合は、wp-content/maintenance.php があればそれを表示して終了する
  4. なければ、標準の短いメッセージを HTTP 503 で返し、Retry-After: 600 ヘッダーを付ける

ステータスコード 503（Service Unavailable）は「いまは一時的に応答できない」という意味で、検索エンジンにも「しばらくしてから再訪してほしい」と伝わる。Retry-After: 600 は、再試行の目安が600秒（10分）であることを示している。HTTPステータスコード全体の意味は「HTTPステータスコードの基礎」で整理している。

判定の中身：ファイルがあっても「10分」で期限切れになる

ここが今回いちばん知っておきたい点である。wp_is_maintenance_mode() は、ファイルがあるかどうかだけを見ているわけではない。ソースを読むと、次の順で判定している。

  1. .maintenance が存在しない、またはWordPressのインストール中であれば、メンテナンス中ではない
  2. .maintenance を読み込み、$upgrading の値を取り出す
  3. 現在時刻と $upgrading の差が10分（600秒）以上なら、メンテナンスは終わったものとみなす
  4. 致命的エラーの検出処理（wp_scrape_key を使うもの）が走っているときは、メンテナンス扱いにしない
  5. フィルター enable_maintenance_mode が false を返したときも、メンテナンス扱いにしない

3番の「10分」の確認として、サーバー上の PHP で同じ比較式を実行してみた。

php -r 'define("MINUTE_IN_SECONDS",60); $u=time()-700;
echo (time()-$u)>=10*MINUTE_IN_SECONDS ? "expired" : "active", PHP_EOL;'
# → expired   （700秒前に作られたファイルは期限切れ扱い）

つまり、更新が途中で止まり .maintenance が削除されないまま残っても、作成から10分たてば、コアの判定上はメンテナンスが終わった扱いになる。少なくとも標準の挙動では、「永遠に準備中のまま」になる設計ではない。

補足: このファイルの有効期限は、ファイルの更新日時ではなく、ファイルの中に書かれた $upgrading の値で決まる。ファイルを手で編集して $upgrading の数値を大きくすると、有効な期間も延びる。

それでも「戻らない」ように見えるとき、確認する順序

標準の挙動が「10分で期限切れ」だとして、それでも画面が戻らないように見える場面はある。原因の切り分けは、次の順に行うと混乱しにくい。

1. まず、更新がまだ続いていないかを確認する

画面を開いた時刻が、更新を始めてから10分以内であれば、ただ待てばよいことが多い。大きなプラグインやWordPress本体の更新は、サーバーの状態によって時間がかかる。更新がまだ走っているのに .maintenance を消してしまうと、更新が中途半端な状態のまま、サイトが通常表示に戻ってしまう。消す前に、更新処理が本当に止まっているのかを確かめるのが先である。

2. wp maintenance-mode で状態を確認する

WP-CLI には、この状態を扱う専用コマンドがある。

wp maintenance-mode status      # 状態を表示
wp maintenance-mode is-active   # 有効かどうかを終了コードで返す
wp maintenance-mode activate    # 有効化（.maintenance を作成）
wp maintenance-mode deactivate  # 無効化（.maintenance を削除）

このブログのサーバーで status を実行すると、Maintenance mode is not active. と表示された。何も起きていない通常時の姿である。status と is-active は読み取りだけなので、状況確認に安心して使える。

3. ファイルの中身と時刻を見る

SSH でルートディレクトリに入り、ls -la で隠しファイルを含めて確認する。

ls -la .maintenance
cat .maintenance        # $upgrading の数値が入っている
date +%s                # 現在の UNIX 時刻

date +%s との差が600秒を超えていれば、コアの判定上は期限切れである。それでも画面が変わらない場合は、メンテナンスモード以外の要因を疑う。

4. メンテナンスモード以外の要因を疑う

  • キャッシュ: ページキャッシュやCDNの設定によっては、メンテナンス画面のレスポンスが一時的に保持され、実際の状態より長く表示されることがある（保持の可否は、使っているキャッシュの設定による）
  • 独自の wp-content/maintenance.php: このファイルがあると、標準メッセージの代わりに表示される。内容によっては、自前の文言や再読み込みの挙動を持つ場合がある
  • 別の原因によるエラー: 更新中の失敗で、メンテナンスとは別に致命的エラーが起きている場合もある。この場合はメンテナンス画面ではなく、エラー画面が出る

5. 更新が本当に止まっていたら、削除してよい

更新処理がすでに終了していて、.maintenance だけが残っているなら、wp maintenance-mode deactivate で削除してよい。そのうえで、更新の対象だったプラグインやテーマが正常に動いているか、管理画面の「更新」画面やサイト表示で確認する。更新が途中で止まった場合は、再度更新を実行して完了させるのが基本である。

運用で意識しておきたいこと

  • 更新のたびに、サイトが503を返す時間がある。アクセスが集中する時間帯の更新は避けるほうが、訪問者にも検索エンジンにも安全である
  • 503 は「一時的」を伝える正しいステータスである。長時間この状態が続くと、検索エンジンの巡回に影響しうるため、止まっているように見えたら早めに確認する
  • 手で .maintenance を作っても、メンテナンス表示にできる。ただし有効期限は10分なので、長時間のメンテナンス表示が必要なら、wp-content/maintenance.php や、メンテナンス用のプラグインを使う設計が別に必要になる
  • 複数サイトを扱う場合は、サイトごとの状態を把握しておく。一括で更新を流すときは、どのサイトが更新中で、どのサイトが完了しているかの記録が、あとで原因を切り分ける助けになる

複数のサイトをまとめて扱う場面での WP-CLI の使い方は、「wp cli alias で複数サイトを操作する」の記事でも触れている。

まとめ

WordPressのメンテナンスモードは、ルートに置かれる .maintenance というファイル1つで成り立っている。更新の開始時に $upgrading = <作成時刻>; を書き込み、完了時に削除する。リクエストのたびにコアが確認し、ファイルが存在していても、作成から10分を過ぎれば期限切れとして通常表示に戻す。

そのため、更新が途中で止まって .maintenance が残っても、標準の挙動では、10分ほどで判定が外れる。それでも戻らないように見えるときは、更新がまだ続いていないか、キャッシュや独自の maintenance.php が表示を保っていないかを確認し、更新が確かに終わっているなら wp maintenance-mode deactivate で整理する。「消す前に、本当に止まっているかを確かめる」という順序を守っておけば、この画面は落ち着いて扱える。