> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 部署

> 將 Laravel 應用程式部署至正式環境的設定、最佳化與維運指南

## 簡介

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

## 部署流程

```mermaid theme={null}
flowchart TD
    A["推送程式碼"] --> B["php artisan optimize"]
    B --> C["以 Nginx / FrankenPHP 提供服務"]
    C --> D["php artisan reload"]
    D --> E["重新啟動佇列 worker<br>Reverb / Octane"]
    E --> F["部署完成"]
```

## 伺服器需求

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` 移動到專案根目錄，否則會將機密設定檔暴露在外。

```nginx theme={null}
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](https://frankenphp.dev/) 是以 Go 撰寫的現代 PHP 應用程式伺服器。
只需下列指令便可啟動 Laravel 應用程式：

```shell theme={null}
frankenphp php-server -r public/
```

HTTP/3、現代化壓縮、[Laravel Octane](https://laravel.com/docs/octane) 整合、獨立可執行檔等進階功能請參閱 [FrankenPHP 的 Laravel 文件](https://frankenphp.dev/docs/laravel/)。

### 目錄權限

Laravel 需要對 `bootstrap/cache` 與 `storage` 目錄有寫入權限。
請將這些目錄的權限設定為 Web 伺服器的程序擁有者可以寫入。

```shell theme={null}
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
```

## 最佳化

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

```shell theme={null}
php artisan optimize
```

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

```shell theme={null}
php artisan optimize:clear
```

### 個別最佳化指令

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

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

<Info>
  執行 `config:cache` 後，請只在設定檔中呼叫 `env()`。
  因為快取後 `.env` 檔案將不再載入，設定檔以外呼叫 `env()` 會回傳 `null`。
</Info>

## 服務重新載入

發布新版本後，佇列 worker、Laravel Reverb、Laravel Octane 等長時間執行的服務需要重新啟動才能使用新程式碼。

```shell theme={null}
php artisan reload
```

此指令會結束可重新載入的服務。
請設定程序監控（如 Supervisor）以自動重新啟動它們。

<Info>
  若你使用 Laravel Cloud，所有服務的優雅重新載入都會自動處理，不需要執行 `reload`。
</Info>

## 除錯模式

`config/app.php` 的 `debug` 選項控制錯誤資訊會顯示多少給使用者。
預設會依 `.env` 檔的 `APP_DEBUG` 環境變數值來決定。

<Warning>
  **在正式環境中，`APP_DEBUG` 必須設為 `false`。**
  若在正式環境保持 `APP_DEBUG=true`，可能會將資料庫連線資訊或私鑰等機密設定值暴露給終端使用者。
</Warning>

```ini theme={null}
# .env（正式環境）
APP_DEBUG=false
```

## 健康檢查路由

Laravel 內建了健康檢查路由，可用來監控應用程式狀態。
可與 uptime monitor、負載平衡器或 Kubernetes 等調度系統整合。

預設會提供 `/up` 端點，應用程式正常啟動時回傳 `200`，若啟動時發生例外則回傳 `500`。

可在 `bootstrap/app.php` 自訂 URI。

```php theme={null}
->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](https://cloud.laravel.com)。
這是為 Laravel 最佳化的 PaaS，提供託管的運算、資料庫、快取與物件儲存。

由 Laravel 開發團隊親自調校，能與框架無縫整合。

### Laravel Forge

若你想自己管理伺服器，但不想花力氣安裝 Nginx、MySQL 等各種服務，[Laravel Forge](https://forge.laravel.com) 會非常方便。

Forge 可在 DigitalOcean、Linode、AWS 等主流雲端供應商建立伺服器，並自動安裝與管理 Nginx、MySQL、Redis、Memcached、Beanstalk 等工具。

## 下一步

<Card title="部署 — 官方文件" icon="arrow-right" href="https://laravel.com/docs/deployment">
  在官方文件中確認最新的部署設定細節。
</Card>


## Related topics

- [Laravel Cloud CLI — 從終端機操作 Laravel Cloud](/zh-TW/blog/laravel-cloud-cli.md)
- [Feedable](/zh-TW/packages/feedable/index.md)
- [打包 Copilot CLI](/zh-TW/packages/laravel-copilot-sdk/bundle-cli.md)
- [laravel/agent-skills — Laravel 官方 AI Agent 技能集](/zh-TW/blog/agent-skills-introduction.md)
- [Labeler](/zh-TW/packages/laravel-bluesky/labeler.md)