部署 - Knowledge of Laravel

簡介

將 Laravel 應用程式部署至正式環境時，需要做好各項準備以確保能高效運作。本指南說明將 Laravel 應用程式順利部署至正式環境的重要要點。

部署流程

伺服器需求

Laravel 框架具有以下系統需求：需 PHP 8.3 以上，並具備下列 PHP 擴充模組：

擴充模組	說明
Ctype	字元類型檢查
cURL	HTTP 通訊
DOM	XML/HTML 的 DOM 操作
Fileinfo	MIME 類型偵測
Filter	資料過濾
Hash	雜湊函式
Mbstring	多位元組字串處理
OpenSSL	加密
PCRE	正規表達式
PDO	資料庫連線
Session	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

最佳化

部署至正式環境時，快取設定、事件、路由與 view 可提升效能。可透過 optimize 指令一次快取所有項目。

php artisan optimize

要移除快取請使用 optimize:clear。

php artisan optimize:clear

個別最佳化指令

optimize 會統一執行下列指令。你也可以依需要單獨執行。

指令	說明
`php artisan config:cache`	將設定檔合併為單一檔案並快取
`php artisan event:cache`	快取事件到 listener 的對應
`php artisan route:cache`	快取路由定義，加速路由註冊
`php artisan view:cache`	預先編譯 Blade view 以加速請求

執行 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 內建了健康檢查路由，可用來監控應用程式狀態。可與 uptime monitor、負載平衡器或 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 會非常方便。 Forge 可在 DigitalOcean、Linode、AWS 等主流雲端供應商建立伺服器，並自動安裝與管理 Nginx、MySQL、Redis、Memcached、Beanstalk 等工具。

下一步

部署 — 官方文件

在官方文件中確認最新的部署設定細節。

開始使用

基礎

請求處理

資料庫

認證

輔助工具與外部通訊

測試與部署

AI 開發輔助

部署

簡介

部署流程

伺服器需求

伺服器設定

Nginx

FrankenPHP

目錄權限

最佳化

個別最佳化指令

服務重新載入

除錯模式

健康檢查路由

使用 Laravel Cloud 或 Forge 部署

Laravel Cloud

Laravel Forge

下一步

部署 — 官方文件

​簡介

​部署流程

​伺服器需求

​伺服器設定

​Nginx

​FrankenPHP

​目錄權限

​最佳化

​個別最佳化指令

​服務重新載入

​除錯模式

​健康檢查路由

​使用 Laravel Cloud 或 Forge 部署

​Laravel Cloud

​Laravel Forge

​下一步

部署 — 官方文件

簡介

部署流程

伺服器需求

伺服器設定

Nginx

FrankenPHP

目錄權限

最佳化

個別最佳化指令

服務重新載入

除錯模式

健康檢查路由

使用 Laravel Cloud 或 Forge 部署

Laravel Cloud

Laravel Forge

下一步