Laravel

Zenavo 識別出的內容

帶有 composer.json（或 index.php）的儲存庫會由 zbpack 建置為 PHP，composer.json 中有 laravel/framework 時識別為 Laravel。映像檔是官方的 php:<version>-fpm，前面是 nginx，監聽 8080 連接埠：

步驟	做什麼
PHP 版本	ZBPACK_PHP_VERSION，其次是 docker-compose.yml 中的 Laravel Sail 執行時，再次是 composer.json 中的 require.php；都沒有時為 8
擴充套件	apcu、bcmath、gd、intl、mysqli、opcache、pcntl、pdo_mysql、sysvsem 和 zip，再加上 composer.json 中的每個 ext-*（使用 PostgreSQL 時加上 "ext-pdo_pgsql": "*"）
安裝	composer install --optimize-autoloader --classmap-authoritative --no-dev；有 package.json 時還會執行 npm install（Node.js 22）
最佳化	php artisan optimize、config:cache、event:cache、route:cache、view:cache，如果 package.json 有 build 指令碼再執行 npm run build
提供服務	nginx 提供 public/，並把 PHP 請求交給 php-fpm

Laravel 的設定

最佳化步驟在建置期間執行，而建置拿不到服務的變數（建置方案）。config:cache 會快取一份沒有資料庫和 APP_KEY 的設定，之後 Laravel 在執行時會忽略這些變數。請關閉建置時的最佳化，改為在服務啟動時執行。在 設定 → 建置 → zbpack 選項 中：

ZBPACK_PHP_OPTIMIZE=false
ZBPACK_BUILD_COMMAND=npm run build
ZBPACK_START_COMMAND=php artisan migrate --force && php artisan optimize && _startup

• ZBPACK_BUILD_COMMAND 建置 Vite 資源，這本來是最佳化步驟做的事。應用沒有前端建置時可以不加。
• _startup 會啟動 nginx 和 php-fpm，必須放在最後。php artisan optimize 用服務的變數快取設定、路由、事件和檢視；資料庫遷移在應用開始提供服務前執行，因為建置時存取不到資料庫。

變數

在服務的 變數 分頁中：

APP_KEY=base64:…
APP_ENV=production
APP_DEBUG=false
APP_URL=${ZENAVO_WEB_URL}
LOG_CHANNEL=stderr
DB_CONNECTION=pgsql
DB_URL=${POSTGRESQL_CONNECTION_STRING}

• 在你的電腦上用 php artisan key:generate --show 生成一次 APP_KEY，並妥善保留：更換它會讓所有人登出，已加密的資料也將無法讀取。
• LOG_CHANNEL=stderr 把 Laravel 的日誌傳送到 執行日誌，而不是寫進容器裡的檔案（每次部署都會丟失）。
• APP_URL 使用名為 web 的連接埠的網域；請使用 網路 分頁中顯示的名稱。
• 使用 MySQL 時，設定 DB_CONNECTION=mysql 和 DB_URL=${MYSQL_CONNECTION_STRING}。Laravel 11 起讀取 DB_URL；更早的版本使用 DATABASE_URL。
• 用 Redis 做快取、工作階段和佇列：REDIS_URL=${REDIS_CONNECTION_STRING}、CACHE_STORE=redis、SESSION_DRIVER=redis。

部署

1. 在專案中新增 PostgreSQL（或 MySQL）（資料庫）。
2. 新增服務 → GitHub，選擇儲存庫和分支，新增上面的變數，點選 下一步。
3. 確認預覽顯示 php，然後點選 部署。在 設定 → 建置 中設定上面的 zbpack 選項，然後重新部署。
4. 在 網路 分頁生成網域或繫結自己的網域。

檔案與佇列

• storage/app 中的上傳檔案每次部署都會丟失。請存放在相容 S3 的儲存中（FILESYSTEM_DISK=s3，配合 AWS_* 變數）。
• 佇列 worker 和定時任務作為同一儲存庫的獨立服務執行：再新增一次這個儲存庫，在 ZBPACK_START_COMMAND 中把啟動指令設為 php artisan queue:work（或 php artisan schedule:work），並且不設 HTTP 連接埠。

常見問題

現象	原因
No application encryption key has been specified	缺少 APP_KEY，或者設定在建置時被快取了。設定 APP_KEY 和 ZBPACK_PHP_OPTIMIZE=false。
應用使用了 SQLite 或 localhost，而不是資料庫	設定在建置時被快取了，當時沒有變數。設定 ZBPACK_PHP_OPTIMIZE=false，並在啟動時執行 php artisan optimize。
could not find driver	缺少 PDO 擴充套件。在 composer.json 的 require 中加上 "ext-pdo_pgsql": "*"。
CSS 和 JavaScript 返回 404	Vite 建置沒有執行。設定 ZBPACK_BUILD_COMMAND=npm run build。
連結和重定向使用了 http://	Laravel 不信任它前面的代理。在 bootstrap/app.php 中用 $middleware->trustProxies(at: '*') 信任代理。