Laravel Vapor部署教程：无服务器实战指南

Laravel Vapor 并非开箱即用的“一键部署”工具，而是深度封装 AWS Lambda 与 API Gateway 的自动化配置层，其部署失败的 90% 案例集中于 502 错误、路由无响应和队列不消费这三大痛点——根源往往不在代码本身，而在 runtime 版本错配、laravel/vapor-core 缺失、vapor.yml 中数据库 ARN 误填为连接字符串、敏感环境变量明文硬编码、worker 函数超时设置过短，以及对 Lambda 事件驱动队列模型（而非传统常驻进程）的误解；真正跑通 Vapor，需要穿透表层命令，直击 AWS 资源生命周期、Lambda 运行时契约与 Laravel 引导机制的深层协同逻辑。

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 资源生命周期。关键差异：

• 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 更影响首屏体验。

文中关于Laravel的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Laravel Vapor部署教程：无服务器实战指南》文章吧，也可关注golang学习网公众号了解相关技术文章。