部署 - Knowledge of Laravel

简介

在将 Laravel 应用部署到生产环境时，需要做一些准备工作，让它尽可能高效地运行。本指南将讲解可靠地进行生产部署的重要要点。

部署流程

服务器要求

Laravel 框架有以下系统要求。需要 PHP 8.3 及以上，以及下表所示的 PHP 扩展。

扩展	说明
Ctype	字符类型检查
cURL	HTTP 通信
DOM	XML/HTML 的 DOM 操作
Fileinfo	MIME 类型检测
Filter	数据过滤
Hash	哈希函数
Mbstring	多字节字符串处理
OpenSSL	加密
PCRE	正则表达式
PDO	数据库连接
Session	会话管理
Tokenizer	PHP token 解析
XML	XML 处理

服务器配置

Nginx

如果使用 Nginx，请以以下配置文件为基础。关键在于将所有请求转发到 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_hide_header X-Powered-By;
    }

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

FrankenPHP

FrankenPHP 是一款用 Go 编写的现代 PHP 应用服务器。只用以下命令就可以启动 Laravel 应用。

frankenphp php-server -r public/

关于 HTTP/3、现代压缩、Laravel Octane 集成、独立二进制文件等高级功能，请参阅 FrankenPHP 的 Laravel 文档。

目录权限

Laravel 需要向 bootstrap/cache 和 storage 目录写入。请设置权限，使 Web 服务器进程用户可以写入这些目录。

chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache

优化

在部署到生产环境时，可以缓存配置、事件、路由和视图来提升性能。使用 optimize 命令可一次完成缓存。

php artisan optimize

要清除缓存，请使用 optimize:clear。

php artisan optimize:clear

各项优化命令

optimize 会同时执行以下多条命令。你也可以按需分别执行。

命令	说明
`php artisan config:cache`	将配置文件合并为单个文件并缓存
`php artisan event:cache`	缓存事件与监听器的映射
`php artisan route:cache`	缓存路由定义以加速路由注册
`php artisan view:cache`	预编译 Blade 视图，加速请求响应

执行 config:cache 之后，只能在配置文件内调用 env() 函数。缓存后 .env 文件将不再被读取，因此在配置文件之外调用 env() 会返回 null。

重载服务

在部署新版本后，队列 Worker、Laravel Reverb、Laravel Octane 等长时间运行的服务需要重启，以便使用新代码。

php artisan reload

该命令会终止可重载的服务。请配置好进程监视器（例如 Supervisor），使其自动重新启动这些服务。

如果你使用 Laravel Cloud，所有服务的优雅重载都会自动处理，无需运行 reload 命令。

调试模式

config/app.php 中的 debug 选项控制向用户展示的错误信息量。默认使用 .env 文件中 APP_DEBUG 环境变量的值。

在生产环境中，APP_DEBUG 一定要设置为 false。 若在生产环境仍保持 APP_DEBUG=true，可能会向终端用户暴露数据库连接信息、秘钥等敏感配置。

# .env（生产环境）
APP_DEBUG=false

健康检查路由

Laravel 内置了用于监控应用状态的健康检查路由。可与运行时监控、负载均衡、Kubernetes 等编排系统集成。默认提供 /up 端点，应用正常启动时返回 200，启动时抛出异常则返回 500。可以在 bootstrap/app.php 中自定义 URI。

->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/status', // 默认是 /up
)

访问此路由时会派发 Illuminate\Foundation\Events\DiagnosingHealth 事件，因此你可以在监听器中实现额外的数据库或缓存检查。

使用 Laravel Cloud 或 Forge 部署

Laravel Cloud

如果你想要一个完全托管、支持自动扩缩的部署平台，推荐使用 Laravel Cloud。它是一个针对 Laravel 优化的 PaaS，提供托管的计算、数据库、缓存和对象存储。由 Laravel 开发团队亲自调优，与框架无缝集成。

Laravel Forge

如果你希望自己管理服务器，但又不想手动配置 Nginx、MySQL 等各种服务，Laravel Forge 是很方便的选择。它可以在 DigitalOcean、Linode、AWS 等主流云服务商上创建服务器，并自动安装管理 Nginx、MySQL、Redis、Memcached、Beanstalk 等工具。

下一步

部署 — 官方文档

你可以在官方文档中查看最新的部署配置详情。

​简介

​部署流程

​服务器要求

​服务器配置

​Nginx

​FrankenPHP

​目录权限

​优化

​各项优化命令

​重载服务

​调试模式

​健康检查路由

​使用 Laravel Cloud 或 Forge 部署

​Laravel Cloud

​Laravel Forge

​下一步

部署 — 官方文档

简介

部署流程

服务器要求

服务器配置

Nginx

FrankenPHP

目录权限

优化

各项优化命令

重载服务

调试模式

健康检查路由

使用 Laravel Cloud 或 Forge 部署

Laravel Cloud

Laravel Forge

下一步