Laravel如何开启和关闭维护模式_站点维护状态切换-Laravel-PHP中文网

Laravel如何开启和关闭维护模式_站点维护状态切换

冰火之心

发布： 2025-09-18 08:43:01

原创

977人浏览过

Laravel维护模式通过php artisan down开启，php artisan up关闭，期间返回503状态码并显示自定义维护页面；可配合--secret、--refresh等参数优化体验，并需注意缓存、权限及CDN问题；部署时应集成维护命令以保障更新平稳。

laravel如何开启和关闭维护模式_站点维护状态切换

Laravel的维护模式，说白了，就是给你的网站盖上一个“施工中”的牌子，让访问者知道你正在对它进行一些操作。开启和关闭这个模式，核心就是通过Artisan命令行工具，用

php artisan down

登录后复制

来让网站进入维护状态，再用

php artisan up

登录后复制

来恢复正常访问。这套机制既简单又高效，是我们在部署更新、修复bug或者进行数据迁移时，保护用户体验和数据完整性的一个基本操作。

解决方案

要让你的Laravel应用进入维护模式，你只需要在项目的根目录下执行一个简单的Artisan命令：

php artisan down

登录后复制

这个命令一执行，你的网站就会立即返回一个503状态码（Service Unavailable），并且显示一个默认的维护页面。所有非白名单IP或秘密链接的访问都会被拦截。

如果你想在维护期间，自己或者团队成员还能正常访问网站进行测试，可以使用

--secret

登录后复制

参数生成一个秘密令牌：

php artisan down --secret="your-secret-token"

登录后复制

这样，当你访问

https://your-domain.com/your-secret-token

登录后复制

时，就可以绕过维护模式。这个秘密令牌会设置一个cookie，让你在之后访问网站时也能保持正常状态。

另外，你可能希望在维护模式下，浏览器能够自动刷新页面，等待网站恢复。这时可以使用

--refresh

登录后复制

参数，指定一个秒数：

php artisan down --refresh=60

登录后复制

这会让浏览器每60秒尝试刷新一次页面。

如果你想自定义返回的HTTP状态码，而不是默认的503，可以使用

--status

登录后复制

参数：

php artisan down --status=500

登录后复制

当维护工作完成，需要让网站恢复正常访问时，也很简单：

php artisan up

登录后复制

这个命令会删除Artisan生成的

storage/framework/down

登录后复制

文件，网站就会立即恢复正常运行。

维护模式下用户体验如何优化？

坦白说，用户遇到“网站维护中”的页面，体验通常不会太好。但我们总能做些什么来缓解这种不适。在我看来，最直接且有效的方法就是定制一个友好的维护页面。Laravel默认会显示一个非常基础的页面，但我们可以通过创建

resources/views/errors/503.blade.php

登录后复制

文件来完全自定义它。这个页面应该包含什么呢？我觉得至少得有：

明确的通知：告诉用户网站正在维护，而不是出错了。
预计恢复时间：如果可能，给出一个大致的恢复时间，哪怕只是“预计几小时内”也能大大降低用户的焦虑。
致歉与感谢：为造成的不便表示歉意，并感谢用户的耐心等待。
联系方式或社交媒体链接：提供一个替代的联系方式，让用户知道在哪里可以获取最新进展。
品牌元素：保持网站的品牌风格，让维护页面看起来也是你网站的一部分，而不是一个突兀的错误页面。

另外，前面提到的

--secret

登录后复制

参数在用户体验优化上也有间接作用。它允许开发和测试人员在维护期间正常访问，这样就能在网站正式上线前，充分测试所有功能，确保恢复后不会出现新的问题，这本身就是对用户体验的极大保障。而

--refresh

登录后复制

参数，虽然不能让用户立即访问，但至少能让他们知道网站可能随时恢复，而不需要手动刷新，这算是一个小小的体贴。我个人觉得，这些细节的考量，能让用户在不便中感受到一份被尊重。

四维时代AI开放平台

查看详情

维护模式可能遇到的常见问题及排查？

在使用维护模式时，我遇到过一些挺让人头疼的问题，这里列举几个常见的，希望能帮到你：

缓存问题导致维护页面不显示或无法退出：这是最常见的问题之一。有时候你执行了
```
php artisan down
```
登录后复制
，但网站依然能访问，或者执行了
```
php artisan up
```
登录后复制
，网站却还是显示维护页面。这通常是配置缓存（
```
php artisan config:cache
```
登录后复制
）、路由缓存（
```
php artisan route:cache
```
登录后复制
）或视图缓存（
```
php artisan view:cache
```
登录后复制
）在作祟。
- 排查：尝试清除所有缓存：
```
php artisan cache:clear
```
  登录后复制
  、
```
php artisan config:clear
```
  登录后复制
  、
```
php artisan route:clear
```
  登录后复制
  、
```
php artisan view:clear
```
  登录后复制
  。尤其是在部署后，如果
```
config:cache
```
  登录后复制
  被运行过，它会把维护模式的状态也缓存起来，导致
```
down
```
  登录后复制
  命令不生效。
storage/framework/down
登录后复制
文件权限问题：
```
php artisan down
```
登录后复制
命令会在
```
storage/framework
```
登录后复制
目录下创建一个
```
down
```
登录后复制
文件。如果这个目录的权限不正确，PHP进程可能无法创建或删除这个文件，导致命令失败或维护模式无法正常开启/关闭。
- 排查：检查
```
storage
```
  登录后复制
  目录及其子目录的权限，确保Web服务器用户（如
```
www-data
```
  登录后复制
  或
```
nginx
```
  登录后复制
  ）有读写权限。通常设置为
```
775
```
  登录后复制
  或
```
777
```
  登录后复制
  。
负载均衡器或CDN缓存了503页面：如果你使用了负载均衡器（如Nginx反向代理）或者CDN服务，它们可能会缓存503页面。即使你的Laravel应用已经恢复正常，用户仍然会看到缓存的维护页面。
- 排查：在
```
php artisan up
```
  登录后复制
  之后，需要手动清除负载均衡器或CDN的缓存。如果可能，在开启维护模式前，设置CDN的缓存规则，让503页面不被缓存或缓存时间极短。
自定义异常处理未生效：如果你在
```
App\Exceptions\Handler.php
```
登录后复制
中自定义了
```
render
```
登录后复制
方法来处理503页面，但发现它没有被调用。
- 排查：确保你的自定义逻辑正确，并且没有其他中间件或配置覆盖了异常处理。有时候，一些第三方包的异常处理可能会优先级更高。

在处理这些问题时，我通常会从最简单的缓存清除开始，然后检查文件权限，最后才考虑更复杂的网络层面或代码逻辑问题。这是一种从表象到本质的排查思路，挺实用的。

如何在部署流程中集成维护模式？

将维护模式集成到部署流程中，是确保网站更新平稳过渡的关键一环。我个人觉得，一个好的部署流程，应该能让用户几乎无感知地完成更新。

一种比较直接的方式是在部署脚本中，将

php artisan down

登录后复制

和

php artisan up

登录后复制

命令作为部署步骤的一部分。

部署前的准备：

进入维护模式：在拉取最新代码、安装依赖或运行迁移之前，首先让应用进入维护模式。
```
php artisan down --secret="deploy-secret" --refresh=30
```
登录后复制
这里使用
```
--secret
```
登录后复制
参数是为了让你自己或CI/CD工具在部署过程中依然能够访问网站进行健康检查，
```
--refresh
```
登录后复制
则给用户一个等待的预期。
代码同步与依赖安装：拉取最新的代码，安装或更新Composer依赖。
```
git pull origin main
composer install --no-dev --optimize-autoloader
```
登录后复制
运行数据库迁移：如果有新的数据库迁移，这时运行它们。
```
php artisan migrate --force
```
登录后复制
```
--force
```
登录后复制
参数在生产环境中是必须的，以避免确认提示。

部署后的收尾：

清除和重建缓存：部署新代码后，旧的配置、路由和视图缓存可能会导致问题，所以务必清除并重建它们。
```
php artisan cache:clear
php artisan config:clear && php artisan config:cache
php artisan route:clear && php artisan route:cache
php artisan view:clear && php artisan view:cache
```
登录后复制
我习惯先清除再重建，这样能确保所有缓存都是基于最新代码生成的。
退出维护模式：所有更新和缓存重建完成后，就可以让网站恢复正常访问了。
```
php artisan up
```
登录后复制

在CI/CD管道中（比如GitHub Actions, GitLab CI, Jenkins），这些命令可以被封装成一个个独立的步骤。例如，在GitHub Actions中，你可以定义一个“Deploy”Job，其中包含“Enter Maintenance Mode”、“Update Code”、“Run Migrations”、“Clear & Cache”和“Exit Maintenance Mode”等Steps。

当然，除了这种“硬性”的维护模式，更高级的部署策略，比如蓝绿部署（Blue/Green Deployment）或者滚动更新（Rolling Update），可以在不完全中断服务的情况下进行部署，它们通过在后台准备新版本实例，然后切换流量，可以最大限度地减少用户感知到的停机时间。不过，对于大多数中小型应用来说，Laravel自带的维护模式已经足够应对日常的部署需求了，关键在于我们如何巧妙地利用它，把对用户的影响降到最低。

以上就是Laravel如何开启和关闭维护模式_站点维护状态切换的详细内容，更多请关注php中文网其它相关文章！