Laravel本番環境で「Class Intervention Image ImageManager not found」エラーが発生する原因と対処法を、OGP画像生成機能の実装事例をもとに詳しく解説します。
こんなお悩みありませんか？
「ローカルでは完璧に動いているのに、本番環境にデプロイした瞬間にIntervention Imageが使えなくなった...」
こんな経験をされた開発者の方、多いのではないでしょうか。今日は実際に私たちFivenine Designで遭遇した事例をもとに、Laravel本番環境でのIntervention Imageトラブルを完全解決する方法をお伝えします。
この記事を読むと：
- 本番環境でのエラーの根本原因が分かります
- 確実な解決方法が身につきます
- 今後同じトラブルを防げるようになります
実際に遭遇したトラブル事例
つい先日、あるクライアント様のWebサイトでSNSシェア用のOGP画像を動的に生成する機能を実装した際の話です。
実装した機能
記事タイトルとサムネイル画像を組み合わせて、自動的にOGP画像を生成する機能でした。
// OGP画像生成のコード例
use Intervention\Image\ImageManager;
use Intervention\Image\Drivers\Gd\Driver;
public function generateOgpImage($title, $thumbnail)
{
$manager = new ImageManager(new Driver());
// ベース画像を作成
$image = $manager->create(1200, 630)->fill('#ffffff');
// サムネイル画像を合成
if ($thumbnail) {
$thumb = $manager->read($thumbnail);
$image->place($thumb, 'top-left', 50, 50);
}
// タイトルを描画
$image->text($title, 600, 400, function($font) {
$font->size(48);
$font->color('#333333');
$font->align('center');
});
return $image->toPng();
}
発生したエラー
ローカル環境では完璧に動作していたのですが、本番環境にデプロイすると以下のエラーが発生しました。
Fatal error: Class 'Intervention\Image\ImageManager' not found
エラーの原因を徹底分析
1. composer install --no-dev問題（最多原因）
最も多い原因がこれです。本番環境で--no-devオプションを使ってインストールすると、開発用パッケージが除外されてしまいます。
# 問題のあるコマンド
composer install --no-dev --optimize-autoloader
Intervention Imageがrequire-devに記載されていると、本番で使えなくなってしまいます。
2. サーバーの画像処理ライブラリ未対応
Intervention ImageはGDまたはImagickが必要ですが、本番サーバーにインストールされていないケースがあります。
3. autoloadキャッシュの問題
composerのautoloadキャッシュが古い状態で、新しいパッケージを認識できていない場合があります。
確実な解決方法：ステップバイステップ
実際に私たちが行った解決方法を順番にご紹介します。
Step 1: composer.jsonの確認と修正
まず、Intervention Imageが正しい場所に記載されているかチェックします。
{
"require": {
"php": "^8.1",
"laravel/framework": "^10.0",
"intervention/image": "^3.0"
},
"require-dev": {
// ここにあったら間違い！
}
}
重要ポイント：
requireセクションに記載する（require-devではない）- バージョン指定を適切に行う
Step 2: サーバー環境の確認
本番サーバーに必要なライブラリがインストールされているか確認します。
// 確認用のコード
phpinfo(); // またはコマンドラインで php -m
必要なモジュール：
- GDの場合:
extension=gd - Imagickの場合:
extension=imagick
Step 3: 本番環境での再インストール
# キャッシュクリア
composer clear-cache
autoloadファイル再生成
composer dump-autoload
パッケージ再インストール
composer install --optimize-autoloader
Laravelキャッシュクリア
php artisan config:clear
php artisan cache:clear
Step 4: 設定の確認とテスト
// config/image.phpの設定確認
return [
'driver' => 'gd', // または 'imagick'
];
// 動作テスト用のコード
use Intervention\Image\ImageManager;
use Intervention\Image\Drivers\Gd\Driver;
try {
$manager = new ImageManager(new Driver());
$image = $manager->create(100, 100)->fill('#ff0000');
echo "Intervention Image is working!";
} catch (Exception $e) {
echo "Error: " . $e->getMessage();
}
よくある失敗パターンと注意点
失敗例1: 一時的な解決に満足してしまう
「とりあえずローカルからファイルをアップロードして動いた」という経験、ありませんか？これは根本解決になっていません。次のデプロイで再び同じ問題が起きてしまいます。
失敗例2: エラーログを十分に確認しない
# 本番サーバーでのログ確認を必ず行いましょう
tail -f /var/log/php_errors.log
tail -f storage/logs/laravel.log
失敗例3: 開発環境と本番環境の差異を軽視
予防策：今後同じトラブルを防ぐために
1. デプロイ前チェックリストの作成
## デプロイ前チェックリスト
- [ ] composer.jsonの依存関係確認
- [ ] 本番サーバーの拡張モジュール確認
- [ ] 環境変数の設定確認
- [ ] ストレージディレクトリの権限確認
- [ ] テスト用エンドポイントの動作確認
2. Dockerを活用した環境統一
# Dockerfile例
FROM php:8.1-fpm
GD拡張のインストール
RUN apt-get update && apt-get install -y
libfreetype6-dev
libjpeg62-turbo-dev
libpng-dev
&& docker-php-ext-configure gd --with-freetype --with-jpeg
&& docker-php-ext-install -j$(nproc) gd
3. CI/CDでの自動テスト組み込み
# GitHub Actions例
name: Test Image Processing
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Setup PHP
uses: shivammathur/setup-php@v2
with:
php-version: '8.1'
extensions: gd, imagick
- name: Test Intervention Image
run: php artisan test --filter=ImageProcessingTest
解決後の効果：クライアント様の声
今回のOGP画像生成機能を実装・修正した結果：
- SNSでのシェア率が約30%向上
- サイトへの流入が20%増加
- クライアント様の手作業が完全自動化
「毎回手動でOGP画像を作成していた作業がなくなって、記事投稿にかかる時間が半分になりました」とお喜びいただけました。
まとめ：まず何をすべきか
Intervention Imageの本番環境エラーを解決するために、今すぐ行うべきこと：
- composer.jsonの確認:
requireセクションにIntervention Imageがあるかチェック - 本番サーバーの拡張確認:
php -m | grep -E 'gd|imagick'でライブラリを確認 - エラーログの詳細確認: 具体的なエラーメッセージを把握
- 段階的な修正: 一つずつ問題を解決していく
技術的なサポートが必要でしたら
Laravelでの画像処理機能実装や、本番環境でのトラブルシューティングでお困りの場合は、お気軽にご相談ください。Fivenine Designでは20年以上の実績をもとに、確実な解決策をご提案させていただきます。
特に「開発は進んでいるけれど、本番環境で思うように動かない」というお悩みは、私たちの最も得意とする分野です。まずはお気軽にお問い合わせください。
