Vapor不是“装了就能跑”的工具，而是AWS Lambda+API Gateway的自动化配置层；90%失败源于依赖错、vapor.yml配错或环境未适配，典型表现为502、路由无响应、队列不消费。

Vapor 不是“装了就能跑”的部署工具，它本质是一套 AWS Lambda + API Gateway 的自动化配置层；90% 的失败都发生在部署后 502、路由无响应、队列不消费这三类问题上。

为什么 vapor deploy 后全是 502？先查这三件事

502 是 Vapor 最典型的“假失败”——不是代码错，而是运行时环境没对齐。

• 本地装了 laravel/vapor（CLI 工具），但 Lambda 层里缺 laravel/vapor-core；vapor-core 才是让 Laravel 在 Lambda 上启动 HTTP Handler 的核心，漏装必 502
• vapor.yml 里没显式声明 runtime: php-82（或匹配你 PHP 版本的 runtime），Vapor 默认用旧版 runtime，和 Laravel 10+ 的 PSR-17 响应契约冲突
• APP_ENV=production 下，Laravel 自动禁用调试模式，但 Vapor 要求所有异常必须被 Vapor\Http\Handler 捕获并转成 API Gateway 兼容格式；如果中间件里有未 catch 的 fatal error（比如扩展缺失），Lambda 直接退出，API Gateway 就返回 502

vapor.yml 中 environments 配置的实际影响

很多人把 vapor.yml 当成 .env 的 YAML 版，其实它控制的是 AWS 资源生命周期。关键差异：

Laravel Creem Agent

Creem 支付商店助理 — 查询订阅、客户、交易、产品，执行心跳检查，管理本地 Laravel支付商店。

下载

• environments.production.database 不是填数据库连接字符串，而是指向一个 Aurora Serverless v2 集群的 ARN（如 arn:aws:rds:us-east-1:123456789012:cluster:my-app-prod）；填普通 MySQL 地址会部署成功但运行时报 Connection refused
• variables 下的值在部署时注入 Lambda 环境变量，但敏感项（如 DB_PASSWORD）必须通过 Vapor UI 加密添加，硬编码在 YAML 里会被 Git 泄露，且 Vapor CLI 会拒绝提交含明文密码的配置
• workers 块定义的是独立的 Lambda 函数，不是 Laravel 的 queue:work 进程；每个 worker 函数默认只处理一个 SQS 队列，不能靠修改 queue:work --tries=3 来重试，得靠 SQS 的 RedrivePolicy 和死信队列

队列任务在 Vapor 里为什么总卡住不执行？

Vapor 的队列不是“后台常驻进程”，而是事件驱动模型：SQS 收到消息 → 触发 worker Lambda → 执行一次 php artisan queue:work → Lambda 销毁。这意味着：

• 不能依赖 QUEUE_CONNECTION=database，Vapor 只原生支持 SQS；改用 database 驱动会导致 worker 启动后立刻退出（无消息可拉）
• worker 函数启动时会自动调用 queue:work --once，不是长运行；所以不要在 AppServiceProvider 里写 Artisan::call('queue:work')，那根本不会生效
• 超时设置必须在 vapor.yml 的 workers 块里配，例如 timeout: 900；Lambda 默认只有 6 秒，连 Composer autoloader 初始化都可能超时

laravel/vapor-core 必须装进生产包，且不能带 --dev

laravel/vapor 是 CLI 工具包，用于本地管理部署配置和命令（如 vapor deploy），而 laravel/vapor-core 才是 Laravel 应用在 Lambda 上运行时真正需要的运行时核心依赖。两者职责完全不同，装错会导致：

• 应用部署后 502 错误、Vapor\Http\Handler 类找不到、或 APP_ENV=production 下路由全挂
• 开发机只需 composer require laravel/vapor --dev（仅本地使用 CLI）
• 生产部署包（即 Lambda 层或 ZIP 包）必须含 laravel/vapor-core，且不能带 --dev
• 若项目已用 laravel/framework 10.x+，注意 vapor-core v4+ 要求 Laravel ≥ 10.27.0，否则 VaporServiceProvider 注册失败

最常被忽略的一点：Vapor 的冷启动延迟真实存在，且无法靠加内存缓解；每次新容器启动都要走完整 Laravel 引导流程，删掉冗余 Service Provider、启用 OPcache、避免在 public/index.php 里手动覆盖 httpApi，这些细节比选 runtime 更影响首屏体验。