Модули в Drupal 10 и 11: типичные грабли и решения

В Drupal 10 и 11 модуль нередко «установлен», но сайт не показывает его блок, маршрут или настройки. Чаще всего причина не в самом PHP-коде: перепутано машинное имя, не загружена конфигурация, не очищен кэш или зависимость поставлена не той версией. Ниже — практический разбор для тех, кто подключает модули через Composer, административный интерфейс или Drush и хочет быстро понять, где именно сломалась цепочка.

Сначала определите, что именно вы устанавливаете

В Drupal есть как минимум три разных действия, которые в разговоре называют установкой модуля:

• файлы модуля добавлены в проект;
• модуль включён в системе;
• его конфигурация импортирована и настроена.

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

Проверьте также версию Drupal и PHP до начала работы. Модуль для Drupal 10 может не поддерживать Drupal 11, а старый модуль может требовать удалённый или переименованный API. Совместимость смотрят на странице проекта и в его файле *.info.yml, а не по названию архива.

Сноска. Машинное имя — короткий идентификатор модуля, например redirect или views. Оно используется в имени файла, URL, конфигурации и командах, поэтому название проекта и машинное имя могут отличаться.

Три способа поставить модуль и цена каждого

Способ установки влияет не только на удобство, но и на повторяемость развёртывания. На рабочем сайте это уже вопрос контроля изменений: ручной архив сложно восстановить, а запись в composer.json можно проверить и повторить на staging.

Для сайта под Git базовым вариантом обычно остаётся Composer: пакет фиксируется в зависимостях, а каталог с кодом не приходится переносить вручную. После изменения зависимостей проверяйте, что обновились и composer.json, и composer.lock. Сам каталог модуля в репозитории может отсутствовать — это нормально для Composer-проекта, если он собирается заново при развёртывании.

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

Типичные ошибки и рабочие приёмы

1. Перепутали название проекта и машинное имя

В каталоге Drupal.org модуль может называться, например, Redirect, а его машинное имя — redirect. В интерфейсе и конфигурации требуется именно машинное имя. Ошибка особенно часто появляется при ручном копировании папки: архив распаковывают с суффиксом версии, меняют имя каталога или помещают модуль внутрь лишнего уровня.

Сверьте имя каталога с файлом redirect.info.yml и проверьте, что файл лежит непосредственно внутри каталога модуля. Если проект использует Composer, не копируйте поверх установленного пакета папку из другого архива: так легко получить смешанные версии файлов.

2. Файлы есть, но Drupal их не видит

В Composer-проекте с отдельным web-каталогом код обычно находится внутри document root, например в web/modules/contrib. Но структура зависит от шаблона проекта. Ищите каталог, который Drupal использует как корень сайта, а не копируйте модуль рядом с ним наугад.

Если в списке расширений нет нужного модуля, проверьте три вещи:

1. модуль находится в каталоге, который сканирует текущая установка Drupal;
2. внутри каталога есть файл *.info.yml с правильным машинным именем;
3. версия модуля совместима с вашей версией Drupal и PHP.

После ручного переноса сначала очистите кэш. Но кэш не исправит неверный путь или повреждённый YAML-файл — в таком случае ошибка вернётся после перестроения контейнера.

3. Не проверили зависимости

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

Не устанавливайте зависимость копированием случайного архива из интернета. Для Composer-проектов добавляйте пакет через Composer и смотрите, какие версии он разрешает. Если Composer сообщает о конфликте, не удаляйте ограничение вслепую: другой пакет может зависеть от старой версии того же компонента.

4. Включили модуль, но не настроили его

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

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

5. Изменили конфигурацию на одном сайте и забыли перенести её

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

Особенно опасен частичный импорт: часть настроек уже изменилась, а оставшиеся объекты не импортировались из-за зависимости. Перед импортом делайте резервную копию и проверяйте список изменений, а не запускайте операцию вслепую на production.

6. Ждёте новый маршрут, блок или шаблон, но видите старое

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

Если очистка кэша не помогла, ищите ошибку в машинном имени, пространстве имён PHP, YAML и правах доступа. Бесконечное повторение очистки кэша не исправляет синтаксическую ошибку.

Когда выбирать какой подход

Ориентируйтесь не на привычку, а на способ эксплуатации сайта:

• Composer выбирайте, если сайт разворачивается из Git, имеет staging или поддерживается несколькими людьми. Это самый предсказуемый путь для обновлений и отката.
• Административную загрузку оставляйте для небольших проектов, где нет командной строки и автоматической сборки. Зафиксируйте версию архива и сохраните инструкцию, откуда он взят.
• Drush используйте для повторяемых операций на сервере, но только после того, как файлы модуля уже попали в проект. Команда включения не скачивает код.

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

Что ломается чаще всего

«The module does not exist.» Drupal не видит модуль в ожидаемом каталоге либо машинное имя в команде указано неверно. Проверьте структуру каталогов и имя файла *.info.yml.

«Unable to install the selected module because it requires…» Не выполнена зависимость или несовместима версия. Установите требуемый компонент тем же способом, что и основной модуль, либо выберите поддерживаемую версию.

«The website encountered an unexpected error. Try again later.» Это общее сообщение. Откройте журнал Drupal и журнал PHP, воспроизведите ошибку ещё раз и ищите первую содержательную строку, а не последующее сообщение о падении страницы.

Ошибка YAML или синтаксическая ошибка PHP. Такой сбой часто появляется после ручного редактирования файла модуля. Верните оригинальный файл из пакета, проверьте отступы YAML и синтаксис PHP той версии, на которой работает сайт.

«Access denied» после включения. Функция существует, но текущей роли не хватает разрешения. Проверьте permission модуля и не выдавайте администраторские права всем пользователям как временный способ диагностики.

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

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

Отдельно проверьте кастомную тему и собственные модули. Они могут использовать внутреннее поведение стороннего модуля, которое не обещано публичным API. После обновления откройте ключевые страницы, формы, cron-задачи и интеграции, а не только административный список расширений.

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

Составьте для проекта короткий реестр: машинное имя модуля, версия Drupal, способ установки, зависимости, включённые разрешения и конфигурация, которую нужно переносить между окружениями. Затем поставьте проблемный модуль на staging с чистого состояния и повторите весь путь: установка файлов, включение, импорт конфигурации, очистка кэша и проверка пользовательского сценария.

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