部署 (Deployment)

簡介 (Introduction)

當你準備將 Laravel 應用程式部署到生產環境時，有一些重要事項可以確保你的應用程式盡可能高效地運行。在本文件中，我們將介紹一些確保 Laravel 應用程式正確部署的重要起點。

伺服器需求 (Server Requirements)

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

伺服器設定 (Server Configuration)

Nginx

如果你將應用程式部署到執行 Nginx 的伺服器上，你可以使用以下設定檔作為設定 Web 伺服器的起點。這個檔案很可能需要根據你的伺服器設定進行自訂。如果你需要協助管理伺服器，請考慮使用完全託管的 Laravel 平台，如 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.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 指令：

frankenphp php-server -r public/

要利用 FrankenPHP 支援的更強大功能，例如其 Laravel Octane 整合、HTTP/3、現代壓縮技術，或將 Laravel 應用程式打包為獨立二進位檔案的能力，請參閱 FrankenPHP 的 Laravel 文件。

目錄權限 (Directory Permissions)

Laravel 需要寫入 bootstrap/cache 和 storage 目錄，因此你應該確保 Web 伺服器處理程序擁有者具有寫入這些目錄的權限。

最佳化 (Optimization)

將應用程式部署到生產環境時，有許多檔案應該被快取，包括你的設定、事件、路由和視圖。Laravel 提供了一個單一、方便的 optimize Artisan 指令，可以快取所有這些檔案。這個指令通常應該作為應用程式部署過程的一部分來呼叫：

php artisan optimize

optimize:clear 方法可用於移除由 optimize 指令產生的所有快取檔案，以及預設快取驅動程式中的所有鍵：

php artisan optimize:clear

在接下來的文件中，我們將討論由 optimize 指令執行的每個細粒度最佳化指令。

快取設定 (Optimizing Configuration Loading)

將應用程式部署到生產環境時，你應該確保在部署過程中執行 config:cache Artisan 指令：

php artisan config:cache

此指令會將所有 Laravel 的設定檔合併為單一的快取檔案，這大大減少了框架在載入設定值時必須存取檔案系統的次數。

[!WARNING] 如果你在部署過程中執行 config:cache 指令，你應該確保只在設定檔中呼叫 env 函式。一旦設定被快取，.env 檔案將不會被載入，所有對 .env 變數的 env 函式呼叫都將回傳 null。

快取事件 (Caching Events)

你應該在部署過程中快取應用程式自動發現的事件與監聽器對應關係。這可以透過在部署期間呼叫 event:cache Artisan 指令來完成：

php artisan event:cache

快取路由 (Optimizing Route Loading)

如果你正在建置一個擁有許多路由的大型應用程式，你應該確保在部署過程中執行 route:cache Artisan 指令：

php artisan route:cache

此指令將所有路由註冊縮減為快取檔案中的單一方法呼叫，從而在註冊數百個路由時提高路由註冊的效能。

快取視圖 (Optimizing View Loading)

將應用程式部署到生產環境時，你應該確保在部署過程中執行 view:cache Artisan 指令：

php artisan view:cache

此指令會預先編譯所有 Blade 視圖，因此它們不會在需要時才編譯，從而提高每個回傳視圖的請求的效能。

除錯模式 (Debug Mode)

config/app.php 設定檔中的 debug 選項決定了向使用者顯示多少錯誤資訊。預設情況下，此選項設定為遵循 APP_DEBUG 環境變數的值，該變數儲存在應用程式的 .env 檔案中。

[!WARNING] > 在生產環境中，此值應始終為 false。如果 APP_DEBUG 變數在生產環境中設定為 true，你將冒著向應用程式的終端使用者暴露敏感設定值的風險。

健康檢查路由 (The Health Route)

Laravel 包含一個內建的健康檢查路由，可用於監控應用程式的狀態。在生產環境中，此路由可用於向正常執行時間監控器、負載平衡器或 Kubernetes 等編排系統報告應用程式的狀態。

預設情況下，健康檢查路由位於 /up，如果應用程式啟動且沒有異常，將回傳 200 HTTP 回應。否則，將回傳 500 HTTP 回應。你可以在應用程式的 bootstrap/app 檔案中設定此路由的 URI：

->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 事件，允許你執行與應用程式相關的額外健康檢查。在此事件的監聽器中，你可以檢查應用程式的資料庫或快取狀態。如果你偵測到應用程式有問題，只需從監聽器拋出異常即可。