Vapor不是“装了就能跑”的工具，而是AWS Lambda+API Gateway的自动化配置层，90%失败源于依赖错、vapor.yml配错或环境未适配，典型表现为502、路由无响应、队列不消费。
直接上结论：Vapor 不是「装了就能跑」的部署工具，它本质是一套 AWS Lambda + API Gateway 的自动化配置层，用错依赖、配错 vapor.yml 或跳过环境适配步骤，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 中 environment 配置的实际影响
很多人把 vapor.yml 当成 .env 的 YAML 版，其实它控制的是 AWS 资源生命周期。关键差异：
Laravel Cloud
下载
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
-
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 函数的
timeout必须 ≥ 单个任务最大执行时间，且不能超过 Lambda 本身上限（目前是 15 分钟）；设成 60 秒但任务要跑 90 秒，就会被强制终止，且不会自动重入队列 - Laravel 的
failed_jobs表在 Vapor 里基本无效——失败任务由 SQS 的maxReceiveCount控制，到阈值后进死信队列，而不是写进 RDS
真正麻烦的不是部署命令本身，而是 Lambda 的冷启动、/tmp 目录生命周期、以及 SQS 消息可见性超时这些底层约束如何映射到 Laravel 的抽象层——这些细节不提前对齐，deploy 成功只是幻觉。
