2026年10月5日

WordPressのメディアライブラリエラーを解決する方法

メディア・画像

はじめに

WordPressの管理画面でメディアライブラリをクリックしても画像が一切表示されない・画像をアップロードしようとすると「HTTPエラー」や「アップロードに失敗しました」と表示される・投稿に挿入した画像が全てリンク切れになっている・サムネイルサイズの画像が生成されず元画像のみが使われているといった問題は、ファイル権限・PHPのメモリ不足・Imagickの設定ミス・データベースの不整合が原因です。

症状・原因

メディアライブラリを開くと「申し訳ありませんが、このコンテンツを読み込めませんでした」が表示される
画像アップロード時に「HTTPエラー」が表示されアップロードが完了しない
wp-content/uploads/フォルダに画像ファイルは存在するがメディアライブラリに表示されない
投稿にサムネイル（アイキャッチ画像）を設定できない

解決手順

ステップ1：メディアライブラリの状態を診断する

# WP-CLIでメディア情報を確認
wp media list --format=table | head -20
wp eval "
echo 'Total attachments: ' . wp_count_posts('attachment')->inherit . PHP_EOL;
echo 'Upload dir: ' . wp_upload_dir()['basedir'] . PHP_EOL;
echo 'Upload URL: ' . wp_upload_dir()['baseurl'] . PHP_EOL;
"

# ファイル権限を確認
wp eval "
\$upload_dir = wp_upload_dir();
echo 'Upload dir writable: ' . (is_writable(\$upload_dir['basedir']) ? 'yes' : 'NO') . PHP_EOL;
echo 'PHP memory_limit: ' . ini_get('memory_limit') . PHP_EOL;
echo 'upload_max_filesize: ' . ini_get('upload_max_filesize') . PHP_EOL;
echo 'Imagick available: ' . (class_exists('Imagick') ? 'yes' : 'no') . PHP_EOL;
"

# 孤立したメディアファイルを検出
wp eval "
global \$wpdb;
\$count = \$wpdb->get_var(
    \"SELECT COUNT(*) FROM {\$wpdb->posts}
     WHERE post_type = 'attachment' AND post_status = 'inherit'\"
);
echo 'Attachments in DB: ' . \$count . PHP_EOL;
"

# アップロードフォルダの権限を修正
chmod 755 wp-content/uploads
find wp-content/uploads -type d -exec chmod 755 {} \;
find wp-content/uploads -type f -exec chmod 644 {} \;

ステップ2：メディアライブラリを修復する

# 孤立した添付ファイルを再登録
wp media import wp-content/uploads/2024/01/*.jpg --preserve-filetime

# メディアのメタデータを再生成
wp eval "
\$attachments = get_posts([
    'post_type'   => 'attachment',
    'post_status' => 'inherit',
    'numberposts' => -1,
    'fields'      => 'ids',
]);
foreach (\$attachments as \$id) {
    \$file = get_attached_file(\$id);
    if (\$file && file_exists(\$file)) {
        wp_update_attachment_metadata(\$id, wp_generate_attachment_metadata(\$id, \$file));
    }
}
echo 'Metadata regenerated for ' . count(\$attachments) . ' attachments.' . PHP_EOL;
"

// functions.php: メディアアップロードのデバッグ
add_filter('wp_handle_upload_prefilter', function(array $file): array {
    error_log(sprintf('[Media] Upload attempt: %s (%s, %d bytes)',
        $file['name'],
        $file['type'],
        $file['size']
    ));
    return $file;
});

add_filter('wp_handle_upload', function(array $upload): array {
    error_log(sprintf('[Media] Upload %s: %s → %s',
        isset($upload['error']) ? 'FAILED' : 'success',
        $upload['file'] ?? 'unknown',
        $upload['error'] ?? 'OK'
    ));
    return $upload;
});

ステップ3：サムネイルを再生成する

# WP-CLIでサムネイルを一括再生成
wp media regenerate --yes

# 特定の画像サイズのみ再生成
wp media regenerate --image-size=thumbnail --yes
wp media regenerate --image-size=medium --yes

# 特定の投稿IDのサムネイルを再生成
wp media regenerate 123 456 789

// functions.php: カスタム画像サイズの登録
add_action('after_setup_theme', function(): void {
    // カスタム画像サイズを追加
    add_image_size('hero-image',   1200, 630,  true);   // クロップあり
    add_image_size('card-thumb',   400,  300,  true);   // クロップあり
    add_image_size('wide-banner',  800,  0,    false);  // 高さは自動

    // 標準サイズの変更
    update_option('thumbnail_size_w', 150);
    update_option('thumbnail_size_h', 150);
    update_option('thumbnail_crop',   1);
});

// Imagickのメモリ制限を設定（大きな画像の処理用）
add_filter('wp_image_editors', function(array $editors): array {
    // GDをImagickより優先（メモリ問題の回避策）
    return array_reverse($editors);
});

ステップ4：アップロードエラーを解決する

// functions.php: アップロード設定の最適化

// ① 許可するMIMEタイプを追加
add_filter('upload_mimes', function(array $mimes): array {
    $mimes['svg']  = 'image/svg+xml';
    $mimes['webp'] = 'image/webp';
    $mimes['avif'] = 'image/avif';
    $mimes['heic'] = 'image/heic';
    return $mimes;
});

// ② アップロードサイズ制限を変更
add_filter('upload_size_limit', function(int $size): int {
    return 64 * MB_IN_BYTES;  // 64MB
});

// ③ アップロードディレクトリをカスタマイズ
add_filter('upload_dir', function(array $dirs): array {
    // 投稿タイプ別にサブフォルダを作成
    if (is_admin() && isset($_POST['post_type']) && $_POST['post_type'] === 'product') {
        $dirs['subdir'] = '/products' . $dirs['subdir'];
        $dirs['path']   = $dirs['basedir'] . $dirs['subdir'];
        $dirs['url']    = $dirs['baseurl'] . $dirs['subdir'];
    }
    return $dirs;
});

# php.ini設定でアップロード制限を変更（.htaccessまたはphp.ini）
# php_value upload_max_filesize 64M
# php_value post_max_size 128M
# php_value memory_limit 256M
# php_value max_execution_time 300

# WP-CLIで設定を確認
wp eval "phpinfo(INFO_CONFIGURATION);" 2>/dev/null | grep -E "upload_max|post_max|memory_limit"

ステップ5：メディア管理を最適化する

// functions.php: メディア最適化設定

// ① 巨大画像を自動リサイズ（デフォルト2560px以下）
add_filter('big_image_size_threshold', function(int $threshold): int {
    return 1920;  // FHD以下に制限
});

// ② WebP自動変換（WordPress 5.8+）
add_filter('image_editor_output_format', function(array $formats): array {
    $formats['image/jpeg'] = 'image/webp';
    $formats['image/png']  = 'image/webp';
    return $formats;
});

// ③ 未使用メディアを定期チェック
add_action('wp_scheduled_media_cleanup', function(): void {
    global $wpdb;
    $unused = $wpdb->get_col(
        "SELECT ID FROM {$wpdb->posts} p
         WHERE post_type = 'attachment'
         AND post_parent = 0
         AND NOT EXISTS (
             SELECT 1 FROM {$wpdb->postmeta} pm
             WHERE pm.meta_value = p.ID
             AND pm.meta_key = '_thumbnail_id'
         )
         LIMIT 100"
    );
    error_log(sprintf('[Media] Found %d potentially unused attachments', count($unused)));
});

注意事項

wp media regenerateでサムネイルを一括再生成する場合、大量の画像がある場合は処理に時間がかかります。--limitオプションで件数を絞りながら実行するか、処理タイムアウトが発生しないようサーバーのmax_execution_timeを延長してください
SVGファイルのアップロードを許可する場合、セキュリティリスクがあります。SVG内にJavaScriptが埋め込まれている場合XSS攻撃の可能性があるため、アップロード前にSVGをサニタイズするか、信頼できるユーザーのみがアップロードできるよう権限を制限してください
WebP自動変換はWordPress 5.8以降で利用可能ですが、サーバーがWebP形式をサポートしている必要があります。imagickまたはgdライブラリがWebPをサポートしているか確認してください

まとめ

WordPressメディアライブラリエラーの解決は①wp media listで添付ファイル確認・wp_upload_dir()での権限チェック・chmod 755でuploads/ディレクトリ権限修正、②wp media importで孤立ファイルを再登録・wp_generate_attachment_metadataでメタデータ再生成・アップロードフィルターでデバッグログ記録、③wp media regenerate --yesでサムネイル一括再生成・add_image_sizeでカスタムサイズ登録・Imagick/GD優先順位の調整、④upload_mimesでWebP/AVIF/HEIC対応・upload_size_limitで64MB制限解除・upload_dirフィルターでフォルダカスタマイズ、⑤big_image_size_threshold=1920で巨大画像制限・image_editor_output_formatでWebP自動変換・未使用メディアの定期チェックの手順で解決します。