Laravelの500エラーを解決する実証済みチェックリスト

まずはログから

「500 Server Error」のページが示すのは、何かが失敗したということだけです。原因はログにあります。まず storage/logs/laravel.log（日次ログを使っている場合はその日のファイル）を確認してください。空の場合、Laravelがログを記録する前にエラーが発生しているため、次にWebサーバーのエラーログと、PHP-FPMまたはLiteSpeedのエラーログを確認します。

エラーを見るために本番サイトで APP_DEBUG=true を設定してはいけません。ページを開いた誰にでも、スタックトレース、環境変数の値、場合によってはパスワードまで表示されてしまいます。代わりにログを読んでください。

tail -n 100 storage/logs/laravel.log
# no entries? check the server logs, for example:
tail -n 100 /var/log/nginx/error.log

1. 権限

Laravelは storage と bootstrap/cache に書き込める必要があります。FTPでのアップロードや別ユーザーでのデプロイの後、これらのフォルダの所有者が誤ったアカウントになっていることがよくあります。ログには「Permission denied」や「failed to open stream」と表示されます。Webサーバーのユーザーに書き込み権限を与えるのはこの2つのフォルダだけにし、プロジェクト全体を書き込み可能にしてはいけません。

2. 環境変数と設定キャッシュ

.env の値の不足や誤りは典型的な原因です。APP_KEY がない（「No application encryption key has been specified」）、データベースのパスワードが誤っている、サーバーに存在しないキャッシュドライバーを指定している、などです。php artisan config:cache を実行した後は、Laravelが実行時に .env を読み込まなくなり、設定ファイル以外での env() の呼び出しは null を返すことに注意してください。.env を変更したら、キャッシュを再構築します。

3. 依存関係とオートロード

デプロイ直後の「Class not found」は、通常 vendor が更新されていないか、オートローダーが古いことを意味します。サーバーで --no-dev と --optimize-autoloader を付けて composer install を実行し、サーバーのPHPバージョンと拡張機能が composer.lock の要件と一致していることを確認してください。

4. データベースとマイグレーション

データベースにまだ存在しないカラムを前提とした新しいコードは、「Unknown column」や「Base table or view not found」などのSQLエラーを引き起こします。本番環境では --force を付けて未実行のマイグレーションを実行してください。あわせて、データベースとRedisに接続でき、接続数が上限に達していないことも確認します。

5. 古いキャッシュとキューワーカー

前回のリリースでキャッシュされたルート、ビュー、設定が、すでに存在しないコードを参照していることがあります。デプロイのたびにクリアして再構築してください。キューワーカーは長時間稼働するプロセスで、再起動するまで古いコードをメモリに保持するため、現在のコードと一致しないエラーでジョブが失敗することがあります。

composer install --no-dev --optimize-autoloader
php artisan migrate --force
php artisan optimize:clear
php artisan config:cache && php artisan route:cache && php artisan view:cache
php artisan queue:restart

6. メモリ、タイムアウト、外部サービス

大量のエクスポート、画像処理、上限のないクエリは、PHPの memory_limit や max_execution_time を超えることがあります。重い処理はキューのジョブに移し、データは分割して処理してください。外部APIの呼び出しには必ずタイムアウトとフォールバックを設定し、1つの遅いプロバイダーのせいでページ全体が停止しないようにします。ステータスコードの違いにも注意してください。502や504は通常、アプリケーションの例外ではなく、PHP-FPMやプロキシのタイムアウトを示しています。

再発を防ぐ

• 常に同じ手順を同じ順序で実行する、ひとつのデプロイスクリプトを使用します。
• お客様より先にエラーに気付けるよう、エラートラッキング（SentryやFlareなど）を導入します。
• Laravelに含まれる /up ヘルスチェックルートと、データベースにアクセスするページを監視します。
• ステージング環境は、PHPのバージョン、拡張機能、キャッシュドライバーを揃え、できる限り本番環境に近づけます。