Laravel维护模式通过php artisan down开启，php artisan up关闭，期间返回503状态码并显示自定义维护页面；可配合–secret、–refresh等参数优化体验，并需注意缓存、权限及CDN问题；部署时应集成维护命令以保障更新平稳。
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
参数，虽然不能让用户立即访问，但至少能让他们知道网站可能随时恢复，而不需要手动刷新，这算是一个小小的体贴。我个人觉得，这些细节的考量，能让用户在不便中感受到一份被尊重。
维护模式可能遇到的常见问题及排查？
在使用维护模式时，我遇到过一些挺让人头疼的问题，这里列举几个常见的，希望能帮到你：
- 缓存问题导致维护页面不显示或无法退出：这是最常见的问题之一。有时候你执行了
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页面不被缓存或缓存时间极短。
- 排查：在
- 自定义异常处理未生效：如果你在
appExceptionsHandler.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 laravel git composer github nginx cookie 浏览器 app 工具 ai php laravel composer nginx 中间件 封装 Cookie Token github gitlab 数据库 jenkins http https bug 负载均衡