- カテゴリ: artisan
- 掲載バージョン: Laravel 12・PHP 8.4
- コマンド:
php artisan down - 関連: up, config:cache, route:cache, view:clear
- 変更履歴: Laravel 8 以降でオプション体系が整理（
secret/with-secret/renderなど）
要点（TL;DR）
- 公開中アプリを 503（メンテナンス） 状態に切り替える
- 最低限の使い方:
php artisan down - よくある罠
概要
php artisan down は、Laravel アプリをメンテナンスモードに切り替え、通常リクエストへメンテナンス用レスポンスを返します。デプロイ中の一時停止や、障害対応で意図的にアクセスを抑止したいときに使います。依存更新のタイミング次第では 503 表示前に落ちうるため、実運用ではオプション併用が定石です。 (Laravel)
構文 / シグネチャ
php artisan down
php artisan down --refresh=15
php artisan down --retry=60
php artisan down --secret="TOKEN"
php artisan down --with-secret
php artisan down --render="errors::503"
php artisan down --redirect=/
オプション
| オプション | 値 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
--refresh | int | なし | Refresh ヘッダを付与し、指定秒数後にブラウザ更新を促す (Laravel) | |
--retry | int | なし | Retry-After ヘッダを指定秒数で返す（ブラウザは無視しがち） (Laravel) | |
--secret | string | なし | 指定トークンのURLにアクセスするとバイパスクッキーを発行し、メンテ中でも閲覧可能にする (Laravel) | |
--with-secret | (flag) | なし | Laravel にトークン生成させる。メンテ移行後に表示される (Laravel) | |
--render | view名 | なし | メンテ表示用ビューを 事前レンダ（依存更新中のエラー回避に有効） (Laravel) | |
--redirect | パス | なし | すべてのリクエストを指定URLへリダイレクト (Laravel) |
- 戻り値：なし
- 例外/副作用：メンテナンス状態の切替（デフォルトはファイル方式）。複数サーバで状態を揃えるにはキャッシュ方式も検討 (Laravel)
使用例
最小例
php artisan down
実務例（デプロイで「落ちる前提」を潰す）
# 依存更新中でもメンテ画面を返せるよう、事前レンダビューを使う
php artisan down --render="errors::503" --refresh=15
# ここで composer install / migrate / cache などを実行…
php artisan up
--render を付けると、テンプレートエンジンや依存が完全に起動する前に返せるメンテビューを用意でき、デプロイ中の取りこぼしを減らせます。 (Laravel)
実務例（管理者だけバイパス）
php artisan down --with-secret
# 表示されたトークンURL（例: https://example.com/{token}）へ管理者だけアクセスしてクッキー発行
トークンはURLに載るため、英数字＋ダッシュ中心にし、? や & など意味を持つ文字は避けます。 (Laravel)
よくある落とし穴・注意
- 複数サーバ構成（LB配下など）
デフォルトはファイル方式なので、各サーバでdownが必要です。1台だけdownしても他が生きていると挙動が割れます。 (Laravel)
1回の実行で全台に反映したいなら、.envのメンテナンスドライバをキャッシュ方式へ（共有ストア必須）。 (Laravel) - キューは処理されない
メンテ中はキュージョブが処理されず、up後に再開します（停止して見えるのは正常）。 (Laravel) - 「メンテに入れる＝安全」ではない
down実行直後に依存更新を始めると、レースでエラーが見えることがあります。--renderを優先。 (Laravel)
代替・関連APIとの比較
down/up：アプリ側で 503 を返す（手軽、単体〜中規模向け）- ロードバランサ/リバプロで切替：アプリを触らず遮断（大規模・ゼロダウンタイム構成向け）
- マネージド基盤のゼロダウンタイムデプロイ：そもそも
downに頼らない選択肢 (Laravel)
選定基準：単体運用・短時間停止なら down、複数台/無停止要件ならインフラ側で吸収。
テスト例（Pest）
use Illuminate\Support\Facades\Artisan;
it('can toggle maintenance mode', function () {
Artisan::call('down', ['--render' => 'errors::503']);
expect(app()->isDownForMaintenance())->toBeTrue();
Artisan::call('up');
expect(app()->isDownForMaintenance())->toBeFalse();
});
トラブルシュート（エラー別）
| 症状/エラー | 原因 | 対処 |
|---|---|---|
| 503 が出ず 500/白画面になる | 依存更新中で起動できずメンテ判定前に落ちている | php artisan down --render="errors::503" を使う (Laravel) |
| サーバによってメンテ表示が出ない | 複数サーバで down 実行が揃っていない（ファイル方式） | 全サーバで down / もしくはキャッシュ方式へ (Laravel) |
| 管理者が入れない | secret のURLにアクセスしていない / トークンが不適切 | トークンURLへアクセスしてクッキー発行、文字種注意 (Laravel) |
スケジューラ例（定期メンテ用途）
// app/Console/Kernel.php
protected function schedule(\Illuminate\Console\Scheduling\Schedule $schedule): void
{
// 例：毎週日曜 03:00 にメンテ開始（定期メンテのときだけ）
$schedule->command('down --render="errors::503" --refresh=30')->sundays()->at('03:00');
}
※ デプロイ用途は “開始と終了” の制御が必要なので、基本は CI/CD の手順内で down→作業→up を明示するのが安全です。
参考リンク
- Laravel公式ドキュメント（Configuration → Maintenance Mode）
https://laravel.com/docs/12.x/configuration (Laravel) - Laravel 12.x 日本語訳（readouble）
https://readouble.com/laravel/12.x/ja/configuration.html (readouble.com) - artisan.page（
downコマンド概要）
https://artisan.page/12.x/down (artisan.page)
