Laravel 13 应用部署：服务器配置、缓存与健康检查

准备将 Laravel 应用部署到生产环境时，可以通过几项配置让应用更有效率地运行。本指南介绍正确部署 Laravel 应用的基本起点，覆盖服务器要求、入口配置、部署优化与健康检查。

服务器要求

Laravel 框架有最低系统要求。Laravel 13 的 Web 服务器需要 PHP 8.3 或更高版本，并启用下列 PHP 扩展：

• Ctype
• cURL
• DOM
• Fileinfo
• Filter
• Hash
• Mbstring
• OpenSSL
• PCRE
• PDO
• Session
• Tokenizer
• XML

服务器配置

Nginx

如果服务器使用 Nginx，可以把以下配置作为起点。需要根据服务器实际情况调整它；如果需要托管服务器管理，也可以评估 Laravel Cloud。

与示例一样，Web 服务器应把应用请求交给 public/index.php。不要把 index.php 移到项目根目录，也不要把整个项目根目录设为公开站点目录，否则敏感配置文件可能暴露到互联网。

server {
    listen 80;
    listen [::]:80;
    server_name example.com;
    root /srv/example.com/public;
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    index index.php;

    charset utf-8;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location = /favicon.ico { access_log off; log_not_found off; }
    location = /robots.txt  { access_log off; log_not_found off; }

    error_page 404 /index.php;
    location ~ ^/index\.php(/|$) {
        fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
        fastcgi_buffer_size 32k;
        fastcgi_buffers 8 32k;
        fastcgi_busy_buffers_size 64k;
        fastcgi_hide_header X-Powered-By;
    }

    location ~ /\.(?!well-known).* {
        deny all;
    }
}

示例使用 HTTP 80 端口和 PHP 8.3 的 FPM 套接字，不能直接代表完整的生产 HTTPS 配置。需要为自己的域名、目录、PHP-FPM 连接方式及 TLS 配置作适配；此处保留官方示例，未在服务器上部署或测试。

FrankenPHP

FrankenPHP 是用 Go 编写的现代 PHP 应用服务器，也可以用来运行 Laravel 应用。启动一个 Laravel PHP 应用，可调用其 php-server 命令：

frankenphp php-server -r public/

要使用 Laravel Octane 集成、HTTP/3、现代压缩或把 Laravel 应用打包为独立二进制等功能，请阅读 FrankenPHP 的 Laravel 文档。

目录权限

Laravel 需要写入 bootstrap/cache 和 storage 目录。应确保 Web 服务器进程对应的用户拥有这两个目录的写入权限。

部署优化

生产部署时，应缓存配置、事件、路由和视图等文件。Laravel 的 optimize Artisan 命令可以集中生成这些缓存，通常应把它纳入应用部署流程：

php artisan optimize

optimize:clear 可以移除 optimize 生成的缓存文件，同时清除默认缓存驱动中的全部键。调用前必须考虑默认缓存中业务数据的影响：

php artisan optimize:clear

下面分别介绍 optimize 所执行的优化命令。

缓存配置

部署到生产环境时，运行：

php artisan config:cache

此命令把 Laravel 的配置文件合并为一个缓存文件，减少加载配置值时访问文件系统的次数。

生成配置缓存后，仅应在配置文件中调用 env。此后 Laravel 不再载入 .env 文件，依赖该文件的 env 调用会返回 null；读取应用配置应使用配置接口。系统级环境变量与 .env 文件不是同一回事。

缓存事件

部署时可缓存自动发现的“事件—监听器”映射：

php artisan event:cache

缓存路由

如果应用包含大量路由，部署时应运行：

php artisan route:cache

此命令把全部路由注册转换为缓存文件中的一个方法调用，改善大量路由的注册过程。

缓存视图

部署到生产环境时应运行：

php artisan view:cache

此命令预编译全部 Blade 视图，避免每次返回视图的请求都按需编译。

重新加载常驻服务

部署了新应用版本后，队列 worker、Laravel Reverb、Laravel Octane 等常驻服务需要重新加载或重启，才能使用新代码。Laravel 提供一个 reload Artisan 命令来终止这些服务：

php artisan reload

使用 Laravel Cloud 时，它会自动处理全部服务的平滑重载，不需要手动运行该命令。自行托管时，应配置进程监控工具，检测这些进程退出并自动重启；仅终止进程不等于服务已经恢复运行。

调试模式

config/app.php 中的 debug 配置决定向用户展示多少错误信息。默认读取应用 .env 中的 APP_DEBUG 环境变量。

生产环境中应始终设为 false。生产环境启用 APP_DEBUG=true，可能向最终用户暴露敏感配置值。

健康检查路由

Laravel 内置健康检查路由。生产环境可让可用性监控、负载均衡器或 Kubernetes 等编排系统通过此路由检查应用状态。

默认路径是 /up：应用启动时没有异常则返回 HTTP 200，否则返回 HTTP 500。可以在 bootstrap/app.php 中调整路径。官方源代码用下列差异标记表达把 /up 改为 /status：

->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/up', // [tl! remove]
    health: '/status', // [tl! add]
)

上面保留了官方文档的 [tl! remove] 与 [tl! add] 展示标记。它是修改前后的对照，不是可直接复制运行的完整 PHP 片段：实际配置应删除旧 health 行，只留下新的 health: '/status' 参数，不能重复提供同名命名参数。

收到健康路由的 HTTP 请求时，Laravel 还会派发 Illuminate\Foundation\Events\DiagnosingHealth 事件。可以在该事件的监听器中检查数据库、缓存等依赖；发现问题就抛出异常。

默认 HTTP 200 仅说明应用启动时没有异常。数据库、队列或外部服务是否正常，取决于是否为其配置了相应诊断。

使用 Laravel Cloud 或 Forge 部署

Laravel Cloud

Laravel Cloud 是面向 Laravel 的全托管自动扩缩容平台，提供计算、数据库、缓存及对象存储。它由 Laravel 的开发团队为框架配套设计，可以继续按常规方式编写 Laravel 应用。是否采用应依据项目的托管需求。

Laravel Forge

如果希望管理自己的服务器，又不熟悉运行 Laravel 应用所需服务的配置，Laravel Forge 是另一种服务器管理平台。

Forge 可在 DigitalOcean、Linode、AWS 等基础设施平台上创建服务器，并安装、管理 Nginx、MySQL、Redis、Memcached、Beanstalk 等运行应用所需工具。Cloud 和 Forge 都是可选服务；本文没有购买服务或创建服务器。

来源：Laravel 文档贡献者，Deployment；本稿对应 Laravel 13.x 文档及其原始 Markdown。正文及示例采用仓库 MIT 许可。本文进行了中文翻译与排版，补充示例环境、健康检查及差异标记的核验说明，代码块保留原样，未部署或执行。