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: '*') 信任代理。