Laravel Artisan: queue:work
一言概要
キューのジョブを永続的に処理するワーカー起動コマンド。
- カテゴリ: artisan
- バージョン: Laravel 12 / PHP 8.4
- 関連:
queue:listen,queue:restart,queue:flush,queue:failed,queue:retry - 変更履歴: Laravel 5.1 から追加、
queue:listenと統合して永続ワーカーとして推奨
TL;DR
- コマンド:
php artisan queue:work [options] [<connection>] - デフォルトで無限ループ。
--daemonは不要（Laravel 8 以降は自動）。--memoryでメモリ上限を設定し、超過時に自動再起動。
概要
queue:work は指定した接続を監視し、ジョブを取得して実行します。
queue:listen と同様にジョブが無くても待機しますが、永続プロセスとしてデーモン化され、メモリとジョブ数を自動で管理します。
本番環境では supervisor や systemd でプロセスを管理し、再起動やログローテーションを行うのが標準です。
構文 / シグネチャ
php artisan queue:work [options] [<connection>]
| 引数 | 型 | 必須 | 既定値 | 説明 |
|---|---|---|---|---|
connection |
string | 〇 | sync |
使用するキュー接続名 |
--queue |
string | × | * |
処理対象キュー（複数可） |
--daemon |
bool | × | false |
デーモンモード（Laravel 8 以降は自動） |
--once |
bool | × | false |
1ジョブのみ実行して終了 |
--stop-when-empty |
bool | × | false |
キューが空になったら終了 |
--max-jobs |
int | × | null |
実行したジョブ数で停止 |
--max-time |
int | × | null |
実行時間で停止（秒） |
--timeout |
int | × | 60 |
個々のジョブ実行時間上限（秒） |
--sleep |
int | × | 3 |
ジョブが無いときのスリープ時間（秒） |
--tries |
int | × | 0 |
失敗ジョブの再試行回数 |
--memory |
int | × | 128 |
メモリ上限（MB） |
--quiet |
bool | × | false |
出力を抑制 |
--force |
bool | × | false |
エラーがあっても続行 |
戻り値: int (0 = 成功, 1 = 失敗)
例外: Illuminate\Queue\Jobs\JobException などジョブ実行時に投げられる。
使用例
# 最小実行
php artisan queue:work
# Redis キューでメール送信ジョブを永続処理
php artisan queue:work redis \
--queue=emails \
--memory=256 \
--tries=3
Tip：本番では
supervisorで以下のように設定し、永続化とログ管理を行う。
[program:laravel-queue]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/html/artisan queue:work redis --sleep=5 --tries=3
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/log/laravel/queue.log
stopwaitsecs=3600
よくある落とし穴
| 症状 | 原因 | 対処 |
|---|---|---|
| メモリリークでプロセスが停止 | --memory が不足 |
--memory を増やす、または --stop-when-empty を併用 |
| 長時間ジョブ実行でタイムアウト | --timeout が短い |
--timeout を適切に設定 |
| キュー接続が起動しない | 接続設定ミス | config/queue.php を確認、サービスが起動しているか確認 |
| 失敗ジョブが再試行されない | --tries が 0 |
必要に応じて --tries を設定 |
| サービスが再起動してもプロセスが残る | supervisor 設定不備 |
autorestart=true を確認 |
代替・関連APIとの比較
| API | 特徴 | 推奨ケース |
|---|---|---|
queue:listen |
1プロセスで永続実行 | 旧プロジェクトで互換性が必要 |
queue:work |
デーモン化・メモリ管理あり | 現行本番環境 |
queue:restart |
既存ワーカーを再起動 | 設定変更後に実行 |
queue:flush |
すべてのジョブを消去 | テスト・再実行前に使用 |
queue:failed |
失敗ジョブ一覧 | デバッグ・再実行前に確認 |
選定基準：永続実行・メモリ管理・自動再起動が必要なら
queue:work。単一ジョブ実行・スクリプト内で一度だけ処理したい場合は--onceでqueue:work、あるいはqueue:listen。
テスト例（Pest）
it('processes a job from the queue', function () {
Queue::fake();
ProcessOrder::dispatch($order = Order::factory()->create());
Artisan::call('queue:work', ['--once' => true]);
Queue::assertPushed(ProcessOrder::class);
Queue::assertPushed(ProcessOrder::class, function ($job) use ($order) {
return $job->order->id === $order->id;
});
});
トラブルシュート（エラー別）
| エラー | 原因 | 対処 |
|---|---|---|
Connection could not be established |
Redis/Database が起動していない | サービスを起動、接続設定を確認 |
Job timed out |
タイムアウト値が短い | --timeout で延長 |
Out of memory |
メモリ上限不足 | --memory を増やす |
Command Not Found |
Artisan がロードされていない | PHP バージョン・composer autoload を確認 |