Symfony Messenger 正确使用需四步：安装并启用MessengerBundle、配置传输（如Redis/AMQP）、定义可序列化消息类及处理器、精准路由到完整消息类名；任一缺失将导致消息同步执行而非入队。
Symfony Messenger 入门不难，关键在四步：装对组件、配好传输、写清消息、路由准确。跳过任一环节，dispatch 后消息就直接同步执行，根本不会进队列。
安装与启用 Messenger Bundle
仅运行 composer require symfony/messenger 不够，MessengerBundle 必须被显式启用：
- 检查
config/bundles.php是否包含：Symfony\Bundle\MessengerBundle\MessengerBundle::class => ['all' => true] - 若缺失，手动添加并保存
- 运行
php bin/console debug:bundles | grep Messenger，有输出才表示已加载
配置传输（Transport）并选对方案
传输层决定消息存哪、怎么取。开发阶段推荐 Redis，生产环境按运维能力选：
-
Redis（推荐开发/中小项目）：
在.env中设MESSENGER_TRANSPORT_DSN=redis://localhost:6379/myapp_async
（myapp_async是队列名，避免多项目共用 Redis 时串队） -
AMQP（如 RabbitMQ，适合生产高可靠场景）：
MESSENGER_TRANSPORT_DSN=amqp://guest:guest@localhost:5672/%2f/myapp_queue -
Doctrine（仅限低频、临时过渡）：
需先确保doctrine/doctrine-bundle已安装，并运行php bin/console doctrine:migrations:generate创建messenger_messages表 - 验证传输是否就绪：
php bin/console messenger:transport:setup-transports，看到Transport "async" is ready!即成功
定义消息类与处理器
消息类是纯数据载体，必须可序列化；处理器负责实际逻辑：
- 消息类只含简单属性（int/string/array/DateTimeInterface），禁用 Doctrine 实体、闭包、resource、未声明私有属性
- 例如：
src/Message/SendWelcomeEmail.php中只存$userId和$email，不在里面 new UserEntity - 处理器实现
MessageHandlerInterface，用__invoke()接收消息，在内部查库或调外部服务 - 类名和命名空间必须能被自动加载（建议用标准 PSR-4 结构，如
App\Message\SendWelcomeEmail）
正确配置路由（最易错环节）
路由键必须是你 dispatch() 时实例化的那个类的**完整类名**，大小写、反斜杠、命名空间一个都不能错：
- 在
config/packages/messenger.yaml的routing:下写：App\Message\SendWelcomeEmail: async - 绝对不要写成：
App\MessageHandler\SendWelcomeEmailHandler: async或App\Message\:这类前缀匹配 - 验证是否生效：
php bin/console debug:messenger，查看表格中对应消息类的Transport列是否为async - 若显示
sync或为空，说明没命中路由——优先检查拼写、自动加载、是否用了别名或短名
配置完后，用 php bin/console messenger:consume async 启动消费者，再发一条消息测试。加上 --limit=1 --verbose 参数能快速定位序列化或处理异常。
