> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# laravel/symfony-on-cloud — 在 Laravel Cloud 上运行 Symfony 应用

> 对 Laravel 官方新仓库的调查。介绍这个可以让 Symfony Messenger 的托管队列在 Laravel Cloud 上运行的官方 Symfony bundle。

<Info>
  本文是截至 2026 年 6 月的初步调查。`laravel/symfony-on-cloud` 是仍在开发阶段的仓库,后续还会有新功能加入。
</Info>

## 什么是 laravel/symfony-on-cloud

[laravel/symfony-on-cloud](https://github.com/laravel/symfony-on-cloud) 是一个**把 Laravel Cloud 的能力带给 Symfony 应用**的官方 Symfony bundle。仓库于 2026 年 6 月 27 日刚刚公开,非常新。

```mermaid theme={null}
flowchart LR
    A["Symfony 应用"] --> B["laravel/symfony-on-cloud<br>bundle"]
    B --> C["Laravel Cloud<br>托管队列"]
    C --> D["AWS SQS"]
    C --> E["Cloud 面板<br>指标展示"]
```

Laravel Cloud 长期以来是 Laravel 应用专属的平台,而通过这个 bundle,**Symfony 开发者也能用上 Laravel Cloud 的基础设施(托管队列等)**。

第一个功能就是**基于 Symfony Messenger 的托管队列**。README 里写着 “more Laravel Cloud capabilities will follow”,未来还会加入队列之外的能力。

## 安装

```bash theme={null}
composer require laravel/symfony-on-cloud
```

然后在 `config/bundles.php` 中注册 bundle(Symfony Flex 目前还没有对应的 recipe,需要手动加):

```php theme={null}
return [
    // ...
    Laravel\Cloud\Symfony\LaravelCloudBundle::class => ['all' => true],
];
```

## 托管队列

### 基本配置

bundle 提供了一个预设的 transport,名字是 `cloud`。在 Laravel Cloud 环境下会自动注入连接配置,不需要手动设置 DSN。

```yaml theme={null}
# config/packages/messenger.yaml
framework:
    messenger:
        routing:
            '*': cloud
```

<Tip>
  把已有的 Symfony Messenger 应用迁移到 Laravel Cloud 也很方便。Cloud 会自动注入 `MESSENGER_TRANSPORT_DSN=laravel-cloud://managed-queue`,已在使用 `async` transport(`dsn: '%env(MESSENGER_TRANSPORT_DSN)%'`)的应用无需改代码就能运行。
</Tip>

### 多个队列

在 Laravel Cloud 环境中可以创建多个托管队列(例如 `default` 和 `critical`)。每个队列都在独立的 SQS 队列和 worker 上运行。用 `CloudQueueStamp` 把消息 dispatch 到特定队列。

```php theme={null}
use Laravel\Cloud\Symfony\Queue\Messenger\CloudQueueStamp;
use Symfony\Component\Messenger\MessageBusInterface;

$bus->dispatch(new ProcessReport($report), [new CloudQueueStamp('critical')]);
```

不带 stamp dispatch 时会发到默认队列。

### FIFO 队列

名字以 `.fifo` 结尾的托管队列会作为 [FIFO 队列](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/FIFO-queues.html) 处理。消息按严格顺序投递,并会去重。

```php theme={null}
use Laravel\Cloud\Symfony\Queue\Messenger\CloudQueueStamp;

$bus->dispatch(new ProcessOrder($order), [new CloudQueueStamp('orders.fifo')]);
```

默认会自动把队列名作为 group ID,把一个唯一值作为去重 ID。如果需要更细的控制,再加上 `CloudFifoStamp`。

```php theme={null}
use Laravel\Cloud\Symfony\Queue\Messenger\CloudFifoStamp;
use Laravel\Cloud\Symfony\Queue\Messenger\CloudQueueStamp;

$bus->dispatch(new ProcessOrder($order), [
    new CloudQueueStamp('orders.fifo'),
    new CloudFifoStamp(
        messageGroupId: 'customer-'.$order->customerId,
        messageDeduplicationId: 'order-'.$order->id,
    ),
]);
```

### 公平队列

[SQS 公平队列](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-fair-queues.html) 保证一个租户投入大量作业时不会挤压到其他租户。在标准队列上通过设置消息 group ID,SQS 会在租户之间公平地分配处理能力。

```php theme={null}
use Laravel\Cloud\Symfony\Queue\Messenger\CloudMessageGroupStamp;
use Laravel\Cloud\Symfony\Queue\Messenger\CloudQueueStamp;

$bus->dispatch(new ProcessOrder($order), [
    new CloudQueueStamp('orders'),
    new CloudMessageGroupStamp('customer-'.$order->customerId),
]);
```

<Info>
  `CloudMessageGroupStamp` **只用于标准队列**,不能在 FIFO 队列上使用。FIFO 队列的分组要用 `CloudFifoStamp`。
</Info>

### 延迟

用 `DelayStamp` 可以为标准队列设置发送延迟。但受 SQS 限制,**最多 15 分钟**。超过 15 分钟会直接报错(而不是悄悄按 15 分钟执行)。

FIFO 队列不支持延迟,所以在 FIFO 上使用 `DelayStamp` 本身就会报错。

### 重试

处理器失败时,bundle 会把消息还给 SQS,借助 visibility timeout 重新投递。可以等到 SQS 的 visibility timeout 上限(**12 小时**),而不是发送时的 15 分钟。

重试配置使用 Symfony Messenger 标准的 `retry_strategy`。

```yaml theme={null}
# config/packages/messenger.yaml
framework:
    messenger:
        transports:
            cloud:
                retry_strategy:
                    max_retries: 3    # 重试 3 次(共执行 4 次)
                    delay: 1000       # 初始退避(毫秒)
                    multiplier: 2     # 退避倍率
                    max_delay: 0      # 无上限(适用 SQS 12 小时上限)
```

实现了 `UnrecoverableExceptionInterface` 的异常会直接标记为失败,不再重试。

## 本地开发

`cloud` transport 可以在应用中覆盖。本地开发中使用 `sync://`,可以让作业立即同步执行。

```yaml theme={null}
# config/packages/messenger.yaml
when@dev:
    framework:
        messenger:
            transports:
                cloud: 'sync://'
```

如果要完全关闭该功能,设置 `laravel_cloud.queue.enabled: false`。

## 总结

`laravel/symfony-on-cloud` 是一个让 Symfony 应用也能享受到 Laravel Cloud 基础设施的官方 bundle。第一个落地的能力是**托管队列**,涵盖了 Symfony Messenger 集成、多队列、FIFO / 公平队列、重试配置等实用功能。

| stamp                    | 用途               |
| ------------------------ | ---------------- |
| `CloudQueueStamp`        | dispatch 到指定队列   |
| `CloudFifoStamp`         | 控制 FIFO 队列的顺序与去重 |
| `CloudMessageGroupStamp` | 标准队列上的公平分配(租户键)  |

按官方 README 所说,今后还会加入队列之外的 Laravel Cloud 能力。如果 Symfony 应用在 Laravel Cloud 上运行的场景变多,这个 bundle 会非常有价值。

## 相关链接

<CardGroup cols={2}>
  <Card title="laravel/symfony-on-cloud" icon="github" href="https://github.com/laravel/symfony-on-cloud">
    官方仓库与 README
  </Card>

  <Card title="Laravel Cloud" icon="cloud" href="https://laravel.com/cloud">
    Laravel Cloud 官方站点
  </Card>

  <Card title="Symfony Messenger" icon="envelope" href="https://symfony.com/doc/current/messenger.html">
    Symfony Messenger 官方文档
  </Card>

  <Card title="Laravel Cloud 文档" icon="book" href="https://cloud.laravel.com/docs/intro">
    Laravel Cloud 详细文档
  </Card>
</CardGroup>


## Related topics

- [Cloud Sessions](/zh/packages/laravel-copilot-sdk/cloud-sessions.md)
- [Laravel Cloud — Laravel 专用 PaaS 全貌](/zh/blog/laravel-cloud.md)
- [Laravel Cloud - GitHub Copilot SDK for Laravel](/zh/packages/laravel-copilot-sdk/laravel-cloud.md)
- [2026 年 6 月 Laravel 更新](/zh/blog/changelog/202606.md)
- [Laravel Cloud Hibernation(自动休眠)](/zh/blog/laravel-cloud-hibernation.md)