Миграция с Drupal 7 на 10: ошибки и решения

Миграция с Drupal 7 на Drupal 10 чаще всего ломается не на переносе текстовых материалов, а на связях между сущностями, изображениях, ролях, Views и самописных модулях. Это не обновление файлов на сервере: целевой сайт нужно собрать отдельно, перенести данные штатными миграциями, заменить тему и заново реализовать код, для которого нет совместимой версии. Ниже — рабочая схема для Drupal 10.x и типичные ошибки, из-за которых сроки и бюджет проекта растут.

Сначала зафиксируйте границы миграции

Drupal 7 и Drupal 10 используют разные поколения ядра и API. Прямое копирование каталога modules, темы или базы данных не превращает старый сайт в новый. В целевой системе должны появиться новая конфигурация, структура контента и код, совместимый с Drupal 10.

До начала составьте инвентаризацию:

• типы материалов, поля, таксономии, языки и связи между материалами;
• пользователи, роли, способы авторизации и правила доступа;
• файлы, изображения, документы и их публичные URL;
• Views, меню, блоки, формы, правила публикации и интеграции;
• модули Drupal 7, включая самописные и неиспользуемые;
• SEO-адреса, метатеги, редиректы и XML-карту сайта.

Миграция данных — перенос материалов и связанных сущностей из исходной системы в целевую. Это не копирование таблиц: данные преобразуются под модель Drupal 10.

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

Три подхода к переезду

Для Drupal 7 на Drupal 10 обычно выбирают один из трёх вариантов. Разница — в контроле над преобразованием и стоимости подготовки.

Когда выбирать штатные миграции

Если в Drupal 7 используются стандартные типы материалов, поля, таксономии, пользователи и файлы, начните с миграций, которые поставляются с ядром Drupal 10 и его миграционными модулями. Это самый проверяемый путь: перенос можно запускать на копии, очищать результат и повторять после исправления сопоставлений.

Когда нужны собственные миграции

Отдельная логика понадобится для нестандартных таблиц, старых модулей, составных полей, внешних каталогов и правил, которых нет в модели Drupal 10. Не переносите такую таблицу напрямую в базу нового сайта. Сначала опишите, в какую сущность и какое поле попадёт каждое значение, а затем добавьте проверку количества и качества записей.

Типичные ошибки и как их находить

1. Миграция начинается с боевой базы

Работа с единственной копией опасна: повторный запуск, очистка импортированных сущностей или исправление схемы может повредить исходные данные. Сделайте отдельную копию файлов и базы Drupal 7, зафиксируйте дату выгрузки и запретите тестовому окружению отправлять письма или обращаться к боевым интеграциям.

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

2. Сначала переносят статьи, а справочники оставляют на потом

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

Проверка результата: у выборки материалов нет пустых ссылок на термины, авторов и связанные материалы.

3. Игнорируют различия в полях

В Drupal 7 поле могло храниться через модуль, который не поддерживается в Drupal 10, или иметь другую кардинальность, формат даты и правила перевода. Поле «текст» не всегда можно без потерь заменить на другой тип. До импорта составьте таблицу соответствий: старый тип и поле, новое поле, преобразование, допустимое значение и действие при ошибке.

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

4. Файлы переносят, но не проверяют пути

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

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

5. Ожидают, что тема Drupal 7 заработает в Drupal 10

Тему нужно адаптировать или переписать. В Drupal 10 меняются шаблоны, библиотека JavaScript и способы описания темы; старые функции и переопределения могут перестать работать. Сначала соберите минимальную тему с нужными регионами, затем переносите шаблоны по одному, проверяя страницы материалов, Views, формы и адаптивную верстку.

6. Переносят модуль, а не его задачу

У модуля Drupal 7 может не быть версии для Drupal 10. Не подменяйте это копированием каталога или изменением номера версии в файле. Найдите поддерживаемую замену, реализуйте функцию заново или исключите её после согласования требований. Для каждого самописного модуля заранее определите: переносится ли код, только данные или ничего.

7. Не сохраняют URL и правила доступа

Переезд может сохранить весь контент и одновременно сломать поисковый трафик. Зафиксируйте старые адреса, проверьте новые алиасы и подготовьте перенаправления для изменившихся URL. Отдельно протестируйте роли редактора, автора и анонимного посетителя: права Drupal 7 не всегда совпадают с новой конфигурацией.

Как организовать проверку

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

1. Снимите исходные показатели. Посчитайте материалы по типам, термины, пользователей, файлы, комментарии и языковые версии. Сохраните несколько контрольных URL и материалов.
2. Соберите целевой сайт. Установите Drupal 10.x, нужные совместимые модули и тему. Не подключайте его к боевым очередям, почте и платёжным системам.
3. Запустите пробный импорт. Перенесите ограниченный набор данных, изучите журнал и исправьте сопоставления до полного запуска.
4. Сравните контрольные выборки. Проверьте заголовки, даты, авторов, переводы, изображения, ссылки, форматирование и права доступа.
5. Повторите импорт после очистки. Процедура должна быть воспроизводимой. Если команда работает только один раз и вручную, её сложно безопасно применить при повторном переносе.
6. Проведите приёмку перед переключением. Проверьте формы, поиск, страницы 404, редиректы, sitemap, кэш и интеграции. После переключения следите за журналами Drupal, веб-сервера и метриками ошибок.

Где миграция ломается после запуска

Даже успешный импорт не гарантирует рабочий продакшен. Частые проблемы проявляются только после публикации нового сайта:

• кэш показывает старую версию страницы после изменений;
• права доступа скрывают материалы для нужной роли;
• поиск не видит импортированные записи из-за незапущенной индексации;
• внешняя система продолжает отправлять запросы на старые URL;
• редкие типы материалов и старые файлы не попали в тестовую выборку;
• переводы связаны с исходной сущностью неправильно.

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

Что делать дальше

Сначала подготовьте реестр данных и модулей, затем поднимите отдельный Drupal 10.x и выполните пробный импорт на копии Drupal 7. После каждой итерации фиксируйте число сущностей, ошибки, пропущенные поля и список ручных проверок. До переключения измерьте долю доступных старых URL, ошибки 404, время ответа ключевых страниц и успешность отправки форм. Инвалидация кэша и настройка производительности — отдельная задача; здесь важна воспроизводимая миграция, которую можно повторить после исправлений.