--- title: "Laravel Queueの使い方｜ジョブ定義からworker常駐と失敗ジョブ運用まで" url: "https://www.issoh.co.jp/tech/details/17154/" published: 2026-08-30 updated: 2026-09-04 categories: ["Laravel"] publisher: "株式会社一創" --- # Laravel Queueの使い方｜ジョブ定義からworker常駐と失敗ジョブ運用まで Laravelのキューは、コントローラの1行を`dispatch`に置き換えるだけで動き始めます。ところが手元では動いたのに本番で消化されない、同じメールが2通届く、という詰まり方をしやすい機能でもある点に注意が必要です。原因の多くはコードではなく、ワーカーを常駐させる仕組みと再試行の設定値にあります。この記事は2026年8月30日時点の公式ドキュメントと配布ファイルの実測に基づく構成です。同期と非同期の切り分けから整理したいなら、[非同期処理とは？同期処理との違いから実装方式まで実装者目線で解説](https://www.issoh.co.jp/tech/details/13590/)を先に読むと前提が揃います。 ## まとめ：既定接続・常駐方式・再試行設定の判断 - 13系の既定キュー接続は`database`です。Laravel 8から10期の記事にある「`sync`から`database`へ変える」という手順は、新規アプリでは前提が違います。 - ジョブは`make:job`で生成したクラスに`handle`を書くだけです。難所はクラス側ではなく、ワーカーの常駐とタイムアウト設計に寄っています。 - `queue:work`は起動しっぱなしが前提で、単体では落ちたら終わりです。本番ではsupervisorのようなプロセス監視と組み合わせます。 - ワーカー側のタイムアウトは接続側の`retry_after`より必ず短くします。逆にすると同じ処理が2回走ります。 - 再試行回数やバックオフの指定は、13系では`Illuminate\Queue\Attributes`の属性で書く形が中心です。従来のメソッド形式も残っています。 - ドライバ選定は「Redisをすでに運用しているか」と「キューを跨いだ可視化が要るか」の2軸で決まると判断しています。1台構成で流量が読めるうちは`database`のままで足ります。 ## Laravel Queueはジョブ・キュー・ワーカーの3要素で動く 仕組み自体は素朴です。時間のかかる処理を1つのクラス（ジョブ）にまとめ、実行せずに待ち行列（キュー）へ積み、別プロセス（ワーカー）が順に取り出します。HTTPリクエスト内で完結させないので、画像変換や外部API呼び出しが遅くてもレスポンスを即座に返せるのが利点です。PHPという言語のレベルで非同期をどう実現するかは[PHPの非同期処理とは｜Fibers・ReactPHP・AMPHP・Swooleの違いと実装](https://www.issoh.co.jp/tech/details/2764/)で扱っているので、ここではフレームワークが用意した仕組みに絞ります。 ### 接続とキューは別物で、1つの接続に複数の名前付きキューが乗る 用語を整理します。`config/queue.php`の`connections`に並ぶのが「接続」で、ジョブの置き場（データベース、Redis、SQSなど）そのものです。その中に「キュー」という名前付きの区画があり、既定では`default`へ積まれます。`high`や`emails`を作っておくと、ワーカー側で処理順を指定できます。 ``` php artisan queue:work --queue=high,default ``` `high`を先に空にしてから`default`へ移ります。優先度を分けたいだけならキュー名を分ければ済み、接続を増やす必要はありません。 ### 13系の既定接続はdatabaseでjobsテーブルは初期状態にある 実際に配布されている13系の`config/queue.php`を開くと、既定接続はデータベースになっています。 ``` 'default' => env('QUEUE_CONNECTION', 'database'), 'database' => [ 'driver' => 'database', 'connection' => env('DB_QUEUE_CONNECTION'), 'table' => env('DB_QUEUE_TABLE', 'jobs'), 'queue' => env('DB_QUEUE', 'default'), 'retry_after' => (int) env('DB_QUEUE_RETRY_AFTER', 90), 'after_commit' => false, ], ``` 選べるドライバは`sync`、`database`、`beanstalkd`、`sqs`、`redis`、`deferred`、`background`、`failover`、`null`の9種類です。末尾の3つは13系で加わった接続で、後半で触れます。 ジョブを貯める`jobs`テーブルは、既定マイグレーション`0001_01_01_000002_create_jobs_table.php`に含まれます。古い雛形を引き継いだプロジェクトなど、これが無い場合だけ生成コマンドを叩きます。 ``` php artisan make:queue-table php artisan migrate ``` RedisやSQSには追加パッケージが要ります。SQSは`aws/aws-sdk-php ~3.0`、Beanstalkdは`pda/pheanstalk ~5.0`、Redisは`predis/predis ~3.0`かphpredis拡張です。ローカルにRedisコンテナごと用意するなら、[Laravel Sailとは｜sail up/downコマンドの意味と使い方・導入手順](https://www.issoh.co.jp/tech/details/4275/)の構成をそのまま流用できます。 ## make:jobで定義したジョブをdispatchで積むまでの手順 実装は3手です。ジョブクラスを作り、`handle`に処理を書き、呼び出し側で`dispatch`します。 ### ジョブクラスを生成してhandleメソッドへ処理内容を集約する 生成は`make:job`です。`app/Jobs`が無ければ同時に作られます。 ``` php artisan make:job ProcessPodcast ``` 生成されたクラスは`Illuminate\Contracts\Queue\ShouldQueue`を実装しています。これが「同期実行せずキューへ積む」という合図です。インターフェイスを外したクラスは`dispatch`してもその場で実行されます。 ``` productId; } } ``` 同じ`debounceId`のジョブが30秒以内に再投入されると、先行分は破棄されて最後の1件だけが走ります。`maxWait`は先延ばしの上限で、投入が続いても120秒経てば実行されます。重複を防ぎたいだけなら`ShouldBeUnique`もありますが、ロック対応のキャッシュドライバが前提です。 ### トランザクション内でdispatchすると取りこぼしが起きる 代表的な落とし穴は、トランザクション内でのディスパッチです。コミット前にワーカーが拾ってしまう場合があります。ワーカーは別プロセスなので、未コミットのレコードは見えず、「対象が見つからない」という失敗だけが残ります。 ``` 'database' => [ 'driver' => 'database', // 中略 'after_commit' => true, ], ``` 接続設定の`after_commit`を`true`にすると、開いているトランザクションがコミットされるまでディスパッチが保留されます。ジョブ単位なら`afterCommit`メソッドを鎖状に付けます。既定は`false`なので、トランザクションを多用する業務システムでは接続側で`true`に倒すほうが事故が減るでしょう。 ## queue:workをsupervisorで常駐させる本番構成の作り方 ジョブを積んでも、取り出す側が動いていなければ何も起きません。本番でつまずく最大の箇所です。 ### queue:workの主要オプションと既定値を本番運用前に押さえる 起動は`queue:work`で、手動で止めるまで走り続けます。 ``` php artisan queue:work redis --queue=emails --tries=3 --backoff=3 --timeout=60 ``` 実測した既定値と主要オプションを整理します。試行回数の既定が1回である点は、再試行が効かないという問い合わせの典型的な原因です。 | オプション | 既定 | 効果 | | --------------- | ----- | ------------ | | tries | 1回 | ジョブの最大試行回数 | | timeout | 60秒 | 超過でワーカーを異常終了 | | backoff | 即時 | 失敗後の再投入までの秒数 | | sleep | 3秒が慣例 | ジョブが無いときの待機 | | max-jobs | 無制限 | N件処理したら終了する | | max-time | 無制限 | N秒経過したら終了する | | stop-when-empty | 無効 | 空になったら正常終了 | | once | 無効 | 1件だけ処理して終了 | 件数と時間の上限は、長時間走ったワーカーが抱えるメモリを解放する仕掛けです。プロセス監視と組み合わせ、一定間隔でワーカー自身に終了させて再起動を任せます。 開発中は`queue:listen`も使えます。再起動なしでコード変更が反映される代わり、毎回フレームワークを起動し直すため本番には向きません。 ### supervisorの設定ファイルでワーカーを落ちないようにする `queue:work`はタイムアウト超過や`queue:restart`で終了します。放置されないようプロセス監視を挟むのが定番で、Linux環境ではsupervisorを使います。設定ファイルは`conf.d`配下です。supervisorが受け取る標準出力と、アプリがフレームワーク経由で書くログは別系統です。後者のチャンネル設計とファイル権限は[Laravelのログ設定｜logging.phpのチャンネル設計と保持期間・マスキング](https://www.issoh.co.jp/tech/details/17156/)で扱っています。 ``` [program:laravel-worker] process_name=%(program_name)s_%(process_num)02d command=php /home/forge/app.com/artisan queue:work --sleep=3 --tries=3 --max-time=3600 autostart=true autorestart=true stopasgroup=true killasgroup=true user=forge numprocs=8 redirect_stderr=true stdout_logfile=/home/forge/app.com/worker.log stopwaitsecs=3600 ``` `numprocs`が同時に走らせるワーカー数で、この例では8プロセスが並列に処理します。並列数を上げるほど消化は速くなりますが、外部APIのレート制限やデータベース接続数の上限に先にぶつかるため、下流の限界から逆算して決めます。 見落とされやすいのが`stopwaitsecs`です。最長ジョブの実行時間より短いと、停止の途中でsupervisorがプロセスを強制終了し、処理中のジョブが中断されます。公式例が3600秒と大きめなのはそのためです。 ``` sudo supervisorctl reread sudo supervisorctl update sudo supervisorctl start "laravel-worker:*" ``` サーバのプロビジョニングごと任せるなら、supervisorの設定まで見るマネージド寄りの選択肢もあります。範囲と費用は[Laravel Forgeとは｜自動化される範囲・料金・Cloudとの選択基準](https://www.issoh.co.jp/tech/details/17147/)にまとめています。 ### デプロイのたびにqueue:restartでワーカーを入れ替える ワーカーは起動時のアプリケーションをメモリへ読み込んだまま走り続けます。デプロイでコードを差し替えても、走っているワーカーは古いままです。直したはずのバグがキュー経由でだけ再現する現象の多くはこれが原因です。 ``` php artisan queue:restart ``` 処理中のジョブを終えたところで各ワーカーを行儀よく終了させるコマンドです。立ち上げ直すのはsupervisorの役目なので、プロセス監視とセットで初めて機能します。再起動の合図はキャッシュ経由で伝わるため、キャッシュドライバの設定が前提です。デプロイ手順の順序は[Laravelのキャッシュクリア｜cache:clearとoptimize:clearの違いと本番デプロイの手順](https://www.issoh.co.jp/tech/details/17121/)に沿わせます。 常駐プロセスが状態を持ち越す性質は、HTTPリクエスト側でも同じです。そちらの設計は[Laravel Octaneとは｜ワーカー常駐の仕組みと状態リーク・採用条件](https://www.issoh.co.jp/tech/details/17131/)で扱っています。 ### Horizonを入れるのはRedisで運用を可視化したいときだけ ワーカー設定をコードで管理し、スループットや失敗を画面で追いたくなったらHorizonが候補です。`laravel/horizon`の最新は執筆時点で5.48.3（2026年8月10日公開）で、13系に対応します。 ``` 'environments' => [ 'production' => [ 'supervisor-1' => [ 'connection' => 'redis', 'queue' => ['default', 'notifications'], 'balance' => 'auto', 'autoScalingStrategy' => 'time', 'minProcesses' => 1, 'maxProcesses' => 10, 'balanceMaxShift' => 1, 'balanceCooldown' => 3, ], ], ], ``` `balance`を`auto`にすると、キューごとのプロセス数を自動で振り分けます。基準は`autoScalingStrategy`で決まり、`time`は空にするまでの推定時間、`size`は件数を見ます。`balanceMaxShift`と`balanceCooldown`は増減の速さで、この例では3秒ごとに最大1プロセスです。 採用の前提は明確です。Horizonはキュー接続がRedisであることを要求し、Redis Clusterには対応していません。Redisが無い案件では選択肢に入らず、逆に失敗ジョブの追跡へ人手をかけているなら入れる価値があります。Redis互換の実装での差分は[Valkeyとは？Redisとの違い・導入方法・データ型を解説【2026年版】](https://www.issoh.co.jp/tech/details/9652/)で整理しました。メトリクスとして監視基盤へ流すなら、[LaravelでPrometheus＋Grafana監視を実装｜メトリクス収集・可視化・アラート設定](https://www.issoh.co.jp/tech/details/2932/)の構成のほうが既存の監視と揃います。 ## 失敗ジョブをfailed\_jobsで捕捉して再試行する組み方 ジョブは失敗します。外部APIの障害、タイムアウト、想定外のデータと理由は尽きません。設計すべきは「失敗しないこと」ではなく「失敗が記録され、拾い直せること」です。 ### 試行回数とバックオフは属性で書くのがLaravel 13系の書き方 試行上限を超えたジョブは`failed_jobs`テーブルへ入ります。上限はコマンドラインとジョブクラスの両方で指定できますが、13系の公式が前面に出すのは属性による指定です。 ``` use Illuminate\Queue\Attributes\Backoff; use Illuminate\Queue\Attributes\MaxExceptions; use Illuminate\Queue\Attributes\Timeout; use Illuminate\Queue\Attributes\Tries; #[Tries(25)] #[MaxExceptions(3)] #[Timeout(120)] #[Backoff([1, 5, 10])] class ProcessPodcast implements ShouldQueue { // ... } ``` `Tries`が試行回数、`MaxExceptions`が例外を許容する回数です。分けて書けるのは、レート制限で解放されただけの再試行と例外で落ちた再試行を区別したいためです。`Backoff`に配列を渡すと1回目1秒、2回目5秒、3回目以降10秒と段階的に待ちます。外部APIの一時障害にはこれが効きます。 従来の`tries()`や`backoff()`や`retryUntil()`というメソッド形式も残っています。13系へ上げても書き換えは不要ですが、新規なら属性のほうが宣言が1か所にまとまって読みやすいと考えています。 ### retry\_afterとタイムアウトを逆にすると2回実行される ここが最も事故につながる設定です。`retry_after`は接続側の設定で、処理中のまま指定秒数が過ぎたジョブをキューへ戻します。ワーカー側のタイムアウトは、指定秒数を超えたジョブを抱えるワーカー自体を異常終了させる動きです。 前後関係が逆になると何が起きるか。`retry_after`が90秒、タイムアウトが120秒なら、90秒でジョブが別ワーカーへ再投入され、そのあとも元のワーカーは120秒まで同じジョブを処理し続けます。決済や在庫の更新でこれが起きると実害が出ます。タイムアウトは`retry_after`より数秒短く、が鉄則です。 例外がSQSです。SQSだけは`retry_after`を持たず、AWS側の可視性タイムアウトに従います。設定箇所がLaravelの外へ出るため、コンソール側の値との突き合わせが必要です。SQSそのものの性格は[AWS SQS・SNS・SESの違いと使い分け｜3サービスの選定基準を比較](https://www.issoh.co.jp/tech/details/9310/)で整理しています。 ### failed\_jobsの確認と再試行・間引きの運用に使うコマンド 失敗ジョブの操作はArtisanで完結し、手順書には4本を書けば足ります。 ``` php artisan queue:failed php artisan queue:retry ce7bb17c-cdd8-41f0-a8ec-7b4fef4e5ece php artisan queue:retry --queue=emails php artisan queue:retry all php artisan queue:forget 91401d2c-0784-4f43-824c-34f94a33c24d php artisan queue:flush --hours=48 ``` `queue:failed`がジョブID・接続・キュー・失敗時刻の一覧を出し、そのIDを`queue:retry`へ渡すと再投入されます。キュー単位や`all`でのまとめ直しも可能で、原因を直したうえで`all`を打つのが復旧の基本形です。 放置すると`failed_jobs`は際限なく育つので、間引きをスケジューラへ登録しておきます。 ``` use Illuminate\Support\Facades\Schedule; Schedule::command('queue:prune-failed --hours=48')->daily(); ``` 既定では24時間より古いレコードが消えます。ジョブをバッチで束ねている場合は`job_batches`テーブルも同様に育つため、`queue:prune-batches`も日次で回します。 後始末にはジョブクラスの`failed`メソッドを使います。試行上限の超過なら`MaxAttemptsExceededException`、タイムアウトなら`TimeoutExceededException`が渡るので、例外の型による通知の出し分けが可能です。同期ディスパッチの失敗が`failed_jobs`へ入らない点も押さえます。Horizon利用時は`horizon:forget`と`horizon:clear`が別にあります。 ## database・redis・SQSドライバを案件条件で選び分ける 公式ドキュメントは優劣を書きませんが、受託の現場では決め切る必要があります。 ### databaseで始めてよい条件とRedisへ移す判断の線引き `database`を選ぶ条件は「アプリサーバが1台から数台」「1分あたりのジョブが数百件まで」「Redisをまだ運用していない」の3つが揃う場合です。追加のミドルウェアなしで動き、バックアップも既存のデータベース運用に乗ります。13系がこれを既定に据えたのは、大半の案件がこの帯に収まるからだと読んでいます。Node.js側で同じ判断をするなら、Redisに加えてPostgreSQLも選べる[BullMQのバックエンド選択と採用条件](https://www.issoh.co.jp/tech/details/17289/)が比較材料になります。 Redisへ移す線引きは、消化の遅れが目に見えたときです。`database`ドライバはポーリングで取りに行くため、取得のたびに行ロックが必要です。ワーカーを増やすほど競合が増え、並列数を上げても消化量が伸びない地点が来ます。Redisなら`block_for`で到着まで待機でき、無駄なポーリングが減ります。 ``` 'redis' => [ 'driver' => 'redis', 'connection' => env('REDIS_QUEUE_CONNECTION', 'default'), 'queue' => env('REDIS_QUEUE', 'default'), 'retry_after' => (int) env('REDIS_QUEUE_RETRY_AFTER', 90), 'block_for' => 5, 'after_commit' => false, ], ``` `block_for`に`0`を入れるのは避けます。無期限にブロックし、`SIGTERM`の処理が次のジョブまで遅れるため、デプロイ時の停止が効きません。Redis Clusterではキュー名にキーハッシュタグが要り、`queue`の値を波括弧で囲みます。`serializer`と`compression`のRedisオプションがキュードライバで効かない点にも注意します。 ### SQSを選ぶのはアプリ側で可用性を持ちたくない運用体制のとき `sqs`が向くのは、キューの可用性をアプリ側で持ちたくない場合です。冗長化もスケールもAWS側が引き受けます。一方で`retry_after`が効かず可視性タイムアウトがAWS側にあること、メッセージサイズの上限、キュー消去に最大60秒の遅延があることは設計時に織り込みます。Horizonも使えません。 13系で加わった接続も、条件が合えば手数を減らせます。`deferred`はHTTPレスポンス送出後に同じプロセスで、`background`は別のPHPプロセスを起こして処理する接続です。どちらも常駐が要らず、軽い後処理を逃がせます。`failover`は接続を配列で並べ、先頭が使えなければ次へ倒します。 ``` 'failover' => [ 'driver' => 'failover', 'connections' => [ 'redis', 'database', 'sync', ], ], ``` Redisが落ちたらデータベースへ、それも駄目なら同期実行へ、と逃がせます。ジョブを失いたくない処理では有効な備えでしょう。 ### キューの導入を見送るべき場面と同期処理へ切り分ける判断の目安 逆に、キューを入れないほうがよい場面もあります。1つ目は1秒未満で終わり、失敗しても画面でやり直せる処理です。ジョブ化するとテーブルとワーカーとデプロイ手順が増え、得るものより運用の手間が上回ります。2つ目は実行順序が厳密に決まっている処理です。順序保証が要るならキュー名を分けてワーカーを1本に絞るか、同期実行のままにします。3つ目はワーカーを常駐させる置き場が無い構成で、共有レンタルサーバのような環境では`deferred`や`background`で足りる範囲に収めるほうが早道でしょう。 3つ目に当たる場合、判断はアプリ側ではなくインフラ側の設計へ移ります。ワーカーを常駐させるサーバ構成、RedisやSQSの選定、supervisorとデプロイ手順の整備まで引き受ける体制が要るなら、[インフラ構築（AWS・Google Cloud・Azure）](https://www.issoh.co.jp/service/system/aws/)で現行構成の前提から相談いただけます。 ## よくある質問 ### キューに積んだジョブが処理されないのはなぜですか？ 多くはワーカーが動いていないことが原因です。`queue:work`のプロセスが生きているかsupervisorの`status`で確認します。動いているのに消化されないなら、ワーカーが見ているキュー名と積んだ先が食い違っている可能性が濃厚です。`QUEUE_CONNECTION`が`sync`のままなら、そもそも積まれずその場で実行されています。 ### 再試行の設定を書いたのに1回しか実行されないのはなぜですか？ `queue:work`に試行回数を渡していない場合、既定は1回です。ジョブクラス側の`Tries`属性があればその回数が使われますが、どちらも無ければ1回で`failed_jobs`へ入ります。supervisorの`command`行に指定があるか確認してください。 ### コードを直したのに古い挙動のまま動き続けるのはなぜですか？ ワーカーが起動時のコードをメモリへ保持し続けているためです。デプロイ手順に`queue:restart`を組み込み、supervisorに再起動させてください。開発中はローカルだけ`queue:listen`へ切り替える手もあります。 ### 同じジョブが2回実行されてしまう原因は何ですか？ ワーカーのタイムアウトが`retry_after`より長くないか確認します。前後が逆だと、再投入されたあとも元のワーカーが処理を続けるため、二重実行の原因です。SQSではAWS側の可視性タイムアウトが同じ役割を持つので、コンソールの値と突き合わせます。冪等な作りにしておくとより安全でしょう。 ### Horizonとsupervisorはどちらかがあればよいのですか？ 役割が違うので置き換えにはなりません。supervisorはプロセスを見張る仕組み、Horizonはワーカー構成の管理と可視化の仕組みです。Horizonを使う場合も`horizon`コマンド自体をsupervisorで常駐させます。Redis接続が前提な点にも注意します。 ## 関連記事 - [非同期処理とは？同期処理との違いから実装方式まで実装者目線で解説](https://www.issoh.co.jp/tech/details/13590/) - [PHPの非同期処理とは｜Fibers・ReactPHP・AMPHP・Swooleの違いと実装方法](https://www.issoh.co.jp/tech/details/2764/) - [Laravel Octaneとは｜ワーカー常駐の仕組みと状態リーク・採用条件](https://www.issoh.co.jp/tech/details/17131/) - [Laravel Forgeとは｜自動化される範囲・料金・Cloudとの選択基準](https://www.issoh.co.jp/tech/details/17147/) - [LaravelでPrometheus＋Grafana監視を実装｜メトリクス収集・可視化・アラート設定](https://www.issoh.co.jp/tech/details/2932/) - [AWS SQS・SNS・SESの違いと使い分け｜3サービスの選定基準を比較](https://www.issoh.co.jp/tech/details/9310/) - [Valkeyとは？Redisとの違い・導入方法・データ型を解説【2026年版】](https://www.issoh.co.jp/tech/details/9652/) - [Laravel Sailとは｜sail up/downコマンドの意味と使い方・導入手順](https://www.issoh.co.jp/tech/details/4275/) --- 出典: [Laravel Queueの使い方｜ジョブ定義からworker常駐と失敗ジョブ運用まで]()（株式会社一創）