Laravel队列连接配置唯一生效位置是config/queue.php的connections数组;QUEUE_CONNECTION仅指定使用其中某个连接名,不定义连接细节,修改后须执行php artisan config:clear才生效。

队列连接配置在 config/queue.php 文件里
所有队列连接(redis、database、sqs 等)的详细参数都定义在 config/queue.php 的 connections 数组中。这不是“可选位置”,而是唯一生效的配置入口——改其他地方(比如直接在 .env 里写 REDIS_QUEUE=high)不会影响连接行为,只会影响部分连接的子参数(如 queue 名称)。
常见误区是以为改了 .env 里的 QUEUE_CONNECTION=redis 就等于配好了 Redis 连接,其实它只告诉 Laravel “用哪个连接”,真正连哪台 Redis、用哪个数据库连接池、重试时间多少,全靠 config/queue.php 里 connections['redis'] 下的配置项决定。
QUEUE_CONNECTION 环境变量只控制默认连接名
QUEUE_CONNECTION 是一个开关型配置,它的作用非常单纯:从 config/queue.php 的 connections 数组里挑一个键名来用。比如设为 redis,Laravel 就会加载 connections['redis'] 这一整块配置;设为 database,就加载 connections['database']。
- 它不能定义新连接,也不能覆盖连接内部参数(如
retry_after或connection) - 如果
.env里写的是QUEUE_CONNECTION=foo,但config/queue.php中没有connections['foo'],启动队列 worker 时会直接报错:InvalidArgumentException: Unsupported driver [foo] - 修改后必须运行
php artisan config:clear(或php artisan config:cache),否则缓存的旧配置会让改动完全不生效——这是最常被跳过的一步
不同驱动对 config/queue.php 的依赖程度不同
有些驱动看似“轻量”,实则仍强依赖该文件里的结构:
-
sync驱动:不需要额外参数,但connections['sync']仍需存在,否则QUEUE_CONNECTION=sync会失败 -
database驱动:除了table和queue,还隐式依赖failed配置里的database和table,否则失败任务无法入库 -
redis驱动:connection字段必须对应config/database.php中已定义的 Redis 连接名(如default或cache),这里出错会导致Connection refused类错误,而非配置缺失提示 -
sqs或beanstalkd:密钥、端口、region 等全在connections里硬编码或通过env()读取,漏掉任意一项都会在 dispatch 时抛出异常
不要在 .env 里伪造 connections 结构
有人试图用 QUEUE_CONNECTIONS_REDIS_DRIVER=redis 这类方式“绕过” config/queue.php,这是无效的。Laravel 的队列工厂只认 config/queue.php 返回的数组结构,env() 函数只是用来给这个数组里的字段赋值,不是替代整个配置层级。
真正该放在 .env 里的,只有那些需要环境隔离的值,例如:
-
QUEUE_CONNECTION=redis(选连接) -
REDIS_QUEUE=emails(覆盖connections['redis']['queue']) -
QUEUE_FAILED_TABLE=failed_jobs_custom(覆盖failed['table'])
这些变量最终仍要被 config/queue.php 显式消费,否则就是死配置。
复杂点在于:connections 里每个驱动的字段语义不统一(比如 database 用 table,redis 用 queue,sqs 用 queue 但含义是 URL),改错一个字段名,可能只表现为任务静默丢失,而不是报错。


















