Laravel 中文文档

主题

全部文档

部署 ​

简介 ​

当你准备将 Laravel 应用部署到生产环境时，有几件重要事项可帮助应用尽可能高效运行。本文档将介绍一些确保 Laravel 应用正确部署的良好起点。

服务器要求 ​

Laravel 框架有一些系统要求。请确保 Web 服务器具备以下最低 PHP 版本与扩展：

  • PHP >= 8.2
  • Ctype PHP Extension
  • cURL PHP Extension
  • DOM PHP Extension
  • Fileinfo PHP Extension
  • Filter PHP Extension
  • Hash PHP Extension
  • Mbstring PHP Extension
  • OpenSSL PHP Extension
  • PCRE PHP Extension
  • PDO PHP Extension
  • Session PHP Extension
  • Tokenizer PHP Extension
  • XML PHP Extension

服务器配置 ​

Nginx ​

若将应用部署到运行 Nginx 的服务器，可将下列配置文件作为配置 Web 服务器的起点。通常需要根据服务器配置进行定制。若需要协助管理服务器，可考虑使用像 Laravel Cloud 这样的全托管 Laravel 平台。

请确保像下面的配置一样，Web 服务器将所有请求导向应用的 public/index.php 文件。切勿尝试把 index.php 移到项目根目录，因为从项目根目录提供服务会把许多敏感配置文件暴露到公网：

nginx
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.2-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 来服务 Laravel 应用。FrankenPHP 是用 Go 编写的现代 PHP 应用服务器。要用 FrankenPHP 服务 Laravel PHP 应用，只需调用其 php-server 命令：

shell
frankenphp php-server -r public/

若要使用 FrankenPHP 支持的更强大功能，例如其 Laravel Octane 集成、HTTP/3、现代压缩，或将 Laravel 应用打包为独立二进制文件，请参阅 FrankenPHP 的 Laravel 文档。

目录权限 ​

Laravel 需要写入 bootstrap/cache 与 storage 目录，因此请确保 Web 服务器进程所有者对这些目录有写权限。

优化 ​

将应用部署到生产环境时，应缓存多种文件，包括配置、事件、路由与视图。Laravel 提供了一个便捷的 optimize Artisan 命令，可缓存所有这些文件。该命令通常应作为部署流程的一部分执行：

shell
php artisan optimize

可使用 optimize:clear 移除 optimize 命令生成的所有缓存文件，以及默认缓存驱动中的所有键：

shell
php artisan optimize:clear

下文将分别说明由 optimize 命令执行的各项细粒度优化命令。

缓存配置 ​

将应用部署到生产环境时，应确保在部署流程中运行 config:cache Artisan 命令：

shell
php artisan config:cache

该命令会将 Laravel 的所有配置文件合并为一个缓存文件，从而大幅减少框架加载配置值时访问文件系统的次数。

WARNING

若在部署流程中执行 config:cache，请确保仅在配置文件中调用 env 函数。配置被缓存后，.env 文件将不会被加载，所有针对 .env 变量的 env 调用都会返回 null。

缓存事件 ​

应在部署流程中缓存应用自动发现的事件到监听器映射。可通过在部署时执行 event:cache Artisan 命令完成：

shell
php artisan event:cache

缓存路由 ​

若构建的大型应用包含大量路由，应确保在部署流程中运行 route:cache Artisan 命令：

shell
php artisan route:cache

该命令会将所有路由注册压缩为缓存文件中的一次方法调用，从而在注册数百条路由时提升路由注册性能。

缓存视图 ​

将应用部署到生产环境时，应确保在部署流程中运行 view:cache Artisan 命令：

shell
php artisan view:cache

该命令会预编译所有 Blade 视图，避免按需编译，从而提升每个返回视图的请求的性能。

重载服务 ​

INFO

部署到 Laravel Cloud 时无需使用 reload 命令，所有服务的优雅重载会自动处理。

部署新版本应用后，队列 worker、Laravel Reverb 或 Laravel Octane 等长时间运行的服务应重载 / 重启以使用新代码。Laravel 提供统一的 reload Artisan 命令来终止这些服务：

shell
php artisan reload

若未使用 Laravel Cloud，应手动配置进程监控器，以便在可重载进程退出时检测并自动重启它们。

调试模式 ​

config/app.php 配置文件中的 debug 选项决定向用户展示多少错误信息。默认情况下，该选项会遵循存储在应用 .env 文件中的 APP_DEBUG 环境变量。

WARNING

在生产环境中，该值应始终为 false。若生产环境中 APP_DEBUG 为 true，则有向最终用户暴露敏感配置值的风险。

健康检查路由 ​

Laravel 内置健康检查路由，可用于监控应用状态。在生产环境中，该路由可向可用性监控、负载均衡器或 Kubernetes 等编排系统报告应用状态。

默认情况下，健康检查路由位于 /up：若应用启动无异常，返回 200 HTTP 响应；否则返回 500。可在应用的 bootstrap/app 文件中配置该路由的 URI：

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

当向该路由发起 HTTP 请求时，Laravel 还会派发 Illuminate\Foundation\Events\DiagnosingHealth 事件，便于你执行与应用相关的额外健康检查。在该事件的监听器中，可检查数据库或缓存状态。若发现问题，可直接在监听器中抛出异常。

使用 Laravel Cloud 或 Forge 部署 ​

Laravel Cloud ​

若需要专为 Laravel 调优的全托管、可自动扩缩容部署平台，请了解 Laravel Cloud。Laravel Cloud 是面向 Laravel 的稳健部署平台，提供托管计算、数据库、缓存与对象存储。

在 Cloud 上启动 Laravel 应用，体验可扩展的简洁部署。Laravel Cloud 由 Laravel 的创建者精心调优，与框架无缝协作，让你继续按熟悉的方式编写 Laravel 应用。

Laravel Forge ​

若希望自行管理服务器，但不愿手动配置运行稳健 Laravel 应用所需的各种服务，Laravel Forge 是面向 Laravel 应用的 VPS 服务器管理平台。

Laravel Forge 可在 DigitalOcean、Linode、AWS 等多种基础设施提供商上创建服务器。此外，Forge 还会安装并管理构建稳健 Laravel 应用所需的全部工具，例如 Nginx、MySQL、Redis、Memcached、Beanstalk 等。