Laravel默认通过CheckForMaintenanceMode中间件实现维护模式,它在请求最早期检查storage/framework/down文件是否存在,若存在则抛出MaintenanceModeException触发503响应;开启用php artisan down --allow=IP --secret=xxx,关闭用php artisan up,白名单与密钥均自动写入down文件并由中间件原生识别放行。

Laravel 默认就用中间件实现维护模式,核心是 CheckForMaintenanceMode 这个内置中间件,它在请求最早期就介入判断是否该返回 503。你不需要重写或自定义它,除非有特殊需求——比如动态倒计时、IP 白名单逻辑更复杂、或要对接运维系统。
默认中间件怎么工作的
这个中间件位于 Illuminate\Foundation\Http\Middleware\CheckForMaintenanceMode,自动注册在 app/Http/Kernel.php 的全局中间件栈首位。它的逻辑很简单:
- 检查
storage/framework/down文件是否存在 - 如果存在,直接抛出
MaintenanceModeException,触发异常渲染流程 - 不依赖配置加载、数据库或缓存,所以极快且可靠
怎么开启和关闭维护模式
用 Artisan 命令最稳妥:
- 开启:
php artisan down --message="系统升级中" --retry=120 --allow=192.168.1.100 - 关闭:
php artisan up
命令会生成或删除 storage/framework/down 文件(JSON 格式),里面存了时间戳、提示语、重试秒数和允许的 IP 列表。
自定义维护页怎么做
默认页面是硬编码 HTML,不走 Blade 模板。要换页面,得在 app/Exceptions/Handler.php 中捕获异常:
- 在
render()方法里判断$exception instanceof \Illuminate\Foundation\Http\Exceptions\MaintenanceModeException - 然后用
return response()->view('errors.maintenance', [], 503);渲染自己的 Blade 模板 - 注意:维护页里不能调
config()或env(),可用$_ENV或从storage/framework/down文件里读取 message/retry 字段
想加白名单 IP 或 secret 访问怎么办
Laravel 原生已支持,无需改中间件:
- 开启时加
--allow=1.2.3.4或--allow=10.0.0.0/8,对应 IP 可正常访问 - 加
--secret=abc123,访问时带上?secret=abc123参数即可绕过 - 这两个参数都会写进
down文件,CheckForMaintenanceMode自动识别并放行











