Как исключить старые изображения из медиабиблиотеки WordPress без удаления файлов

Ситуация типичная: сайт давно живёт, в /wp-content/uploads/ накопились старые картинки, а в медиабиблиотеке они продолжают мешать — поиск тормозит, редакторы видят мусор, а удалить файлы нельзя, потому что часть из них всё ещё используется в записях, виджетах или кастомных полях. В WordPress нет штатной кнопки «скрыть из медиабиблиотеки, но оставить на сервере», поэтому решение обычно строится вокруг фильтрации списка в админке или переноса части логики в отдельный статус/метку.

Когда это действительно нужно

Не путайте эту задачу с удалением неиспользуемых файлов. Здесь цель другая: оставить файл физически доступным для сайта, но убрать его из повседневной работы редакторов. Это полезно, если:

• в медиабиблиотеке много старых изображений после редизайна;
• часть файлов используется только в старых записях и трогать их рискованно;
• нужно скрыть служебные изображения, которые не должны попадать в выборку при вставке медиа;
• у сайта есть импорт из внешней системы, и в библиотеке смешаны рабочие и архивные файлы.

Диагностика проблемы: что именно мешает

Сначала проверьте, где именно возникает шум. Обычно проблема проявляется в одном из трёх мест: экран «Медиафайлы», выбор изображения в редакторе блоков и поиск по библиотеке. Если изображения не нужны только редакторам, но должны оставаться доступны по URL, удалять их нельзя. Если же они не используются нигде, это уже другая задача — чистка неиспользуемых файлов.

Что проверить перед изменениями

• Есть ли прямые ссылки на файл в контенте, шаблонах или ACF-полях.
• Используется ли изображение как миниатюра записи, фон секции или логотип.
• Есть ли у файла привязка к записи через post_parent.
• Нужно ли скрыть файл для всех ролей или только для редакторов.

Если вы не проверите эти точки, легко получить «чистую» медиабиблиотеку с битым контентом на фронтенде.

Рабочий подход: скрываем файлы по метке, а не удаляем их

Самый предсказуемый вариант — пометить изображения как архивные и фильтровать их в админке. Для этого можно использовать метаполе вложения и исключать такие файлы из запросов медиабиблиотеки.

Ниже пример: добавляем метку _hidden_from_library и скрываем такие вложения в админке. Файлы остаются на сервере и доступны по прямой ссылке.

<?php
add_action('add_attachment', function ($attachment_id) {
    // Метку можно ставить вручную или через отдельный скрипт миграции.
    // Здесь только пример структуры.
});

add_action('pre_get_posts', function (WP_Query $query) {
    if (!is_admin() || !$query->is_main_query()) {
        return;
    }

    global $pagenow;

    if ($pagenow !== 'upload.php') {
        return;
    }

    $meta_query = (array) $query->get('meta_query');
    $meta_query[] = array(
        'key'     => '_hidden_from_library',
        'compare' => 'NOT EXISTS',
    );

    $query->set('meta_query', $meta_query);
});

Этот вариант хорош тем, что не ломает фронтенд и не требует вмешательства в файлы. Но у него есть ограничение: в блоковом редакторе и в некоторых плагинах выбор медиа может использовать свои запросы, поэтому фильтр нужно тестировать именно в тех местах, где у вас реально выбирают изображения.

Если нужен более точный контроль: фильтрация по роли или типу файла

Иногда скрывать нужно не все архивные изображения, а только служебные: например, файлы, загруженные импортом, или картинки, которые не должны быть доступны авторам. Тогда удобнее фильтровать список по роли пользователя или по пользовательскому признаку.

<?php
add_filter('ajax_query_attachments_args', function ($query) {
    if (!current_user_can('manage_options')) {
        $query['meta_query'] = array(
            array(
                'key'     => '_hidden_from_library',
                'compare' => 'NOT EXISTS',
            ),
        );
    }

    return $query;
});

Здесь администратор видит всё, а остальные пользователи — только обычные файлы. Это удобно, если редакторам не нужно работать с архивом, но техподдержке доступ нужен.

Сравнение вариантов

Подход	Что делает	Плюсы	Минусы
Плагин для очистки медиабиблиотеки	Ищет и удаляет неиспользуемые файлы	Быстро, без кода	Риск удалить нужное, если контент хранится нестандартно
Скрытие по метке	Прячет выбранные вложения из списка	Безопасно, обратимо	Нужно один раз настроить метку и фильтр
Удаление файлов с сервера	Физически убирает изображения	Освобождает место	Легко сломать старые записи и шаблоны

Пошаговое решение без потери файлов

Шаг 1. Отметьте изображения, которые нужно скрыть

Проще всего сделать это через отдельный скрипт миграции или вручную для небольшого числа файлов. Если у вас много вложений, можно пройтись по ним через WP-CLI или временный административный инструмент, который проставит метку нужным ID.

Шаг 2. Добавьте фильтр в админке

Используйте pre_get_posts для экрана upload.php и ajax_query_attachments_args для медиапикера. Так вы закроете оба сценария: список в библиотеке и выбор изображения в редакторе.

Шаг 3. Проверьте, что файлы не исчезли с фронтенда

После внедрения откройте несколько старых записей, где эти изображения уже используются. Если картинка отображается по прямой ссылке и в контенте, значит вы скрыли её только в админке, а не удалили физически.

Как проверить, что решение сработало

• Откройте /wp-admin/upload.php и убедитесь, что архивные файлы не показываются в списке.
• В редакторе записи откройте медиабиблиотеку и проверьте, что скрытые изображения не попадают в выборку.
• Откройте старую запись на сайте и убедитесь, что картинка продолжает загружаться.
• Проверьте прямой URL файла в браузере: он должен открываться, если файл не удалён.
• Если используете кэш админки или плагин оптимизации, очистите его и повторите тест.

Частые ошибки и как их исправить

Файлы удалили вместо того, чтобы скрыть

Это самая дорогая ошибка. Если изображение использовалось в контенте, после удаления получите битые ссылки. Исправление только одно: восстановить файл из бэкапа и уже потом настроить скрытие.

Фильтр работает в библиотеке, но не работает в редакторе

Так бывает, если вы повесили логику только на pre_get_posts. Для медиапикера нужен отдельный фильтр ajax_query_attachments_args.

Скрыли слишком много файлов

Если в метаусловии ошиблись и исключили вложения без нужной проверки, в библиотеке пропадут и обычные изображения. Проверьте, что условие действительно ищет только метку архивности, а не любой метапараметр.

Не учли роли пользователей

Редакторам часто нужен урезанный список, а администраторам — полный. Если не разделить доступ, техподдержка начнёт искать «пропавшие» файлы там, где они просто скрыты фильтром.

Безопасность и производительность

Не храните логику скрытия в случайном сниппете без контроля версий. Лучше вынести её в mu-plugin или отдельный мини-плагин, чтобы не потерять при смене темы. Если файлов много, не делайте тяжёлые запросы по post_content на каждом открытии медиабиблиотеки — это быстро ударит по админке.

Если задача шире и вам нужно не только скрыть, но и навести порядок в дублях, служебных файлах и мусоре, имеет смысл посмотреть в сторону инструментов для технической чистки сайта. Например, у Clearfy Pro есть набор функций для удаления дублей и оптимизации служебных элементов: https://wpshop.ru/plugins/clearfy. Но даже с плагином важно сначала понять, что именно вы скрываете и почему.

Когда лучше не прятать, а удалять

Если изображение нигде не используется, не имеет прямых ссылок и не участвует в шаблонах, его можно удалять. Но перед этим стоит проверить не только записи, но и кастомные поля, ACF-группы, блоки в шаблонах и старые страницы, которые могли сохраниться в кэше. Скрытие — это управляемый промежуточный шаг. Удаление — уже финальная операция, и её лучше делать отдельно.

Если вам нужно, я могу сразу подготовить второй вариант статьи — про поиск и удаление неиспользуемых изображений в WordPress без риска сломать контент.