Установка модулей и тем в Drupal: ошибки новичков

В Drupal 10 и 11 модуль или тема могут лежать в нужной папке, но сайт всё равно не сможет их включить: не хватает зависимостей, файлы установлены не в тот каталог или изменения внесены прямо на рабочем сервере. Ниже — последовательность для проекта, управляемого через Composer: она помогает установить расширение, включить его и проверить результат, не ломая обновления.

Перед началом: проверьте способ установки Drupal

Инструкция рассчитана на Drupal 10 или 11, установленный по шаблону drupal/recommended-project, и на Composer 2. В таком проекте файлы сайта обычно находятся в каталоге web, а корневой composer.json лежит рядом с ним. Команды запускают из каталога с этим файлом.

До установки убедитесь, что у вас есть:

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

Версию Drupal и расположение файлов можно посмотреть в административной панели в разделе со сведениями о системе или проверить структуру проекта: наличие корневого composer.json и каталога web — характерный признак Composer-шаблона. Если Drupal установлен иначе, не запускайте команды вслепую: сначала сверьтесь с документацией именно для своей схемы.

Установка модуля через Composer

Для примера возьмём модуль Admin Toolbar. Это расширение интерфейса администратора; команда ниже устанавливает его файлы и зависимости, но не включает модуль автоматически.

1. Перейдите в корень проекта. Откройте каталог, где находится composer.json. Проверка: команда composer validate должна завершиться без ошибки структуры файла. Если Composer сообщает, что файл не найден, вы, скорее всего, находитесь не в том каталоге.
2. Добавьте модуль в зависимости проекта. Выполните composer require drupal/admin_toolbar. Проверка: Composer завершил установку, а в корневом composer.json появилась зависимость drupal/admin_toolbar. Не копируйте модуль вручную в web/modules: Composer не будет учитывать такую копию при разрешении зависимостей и обновлениях.
3. Обновите сведения об установленных расширениях. Если вы используете Drush, выполните drush cr. Команда очищает кеши Drupal; это не включает модуль. Проверка: команда завершается без сообщения об ошибке.
4. Включите модуль. В панели откройте раздел «Расширить», найдите Admin Toolbar и нажмите «Установить». Если модуль сообщает о зависимостях, установите сначала их. Проверка: Drupal показывает подтверждение установки, а модуль отмечен как включённый. В проектах с Drush можно использовать drush en admin_toolbar -y; проверка — успешное завершение команды.

Команда Composer добавляет пакет в проект, а Drupal отдельно регистрирует его как включённое расширение. Это два разных действия — пропуск второго шага часто и создаёт впечатление, что «модуль установился, но его нет».

Установка темы

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

1. Добавьте тему в проект. В корне проекта выполните composer require drupal/gin. Проверка: Composer завершил установку без ошибки, а зависимость появилась в composer.json.
2. Обновите кеши. Выполните drush cr либо используйте соответствующую команду очистки кеша в панели. Проверка: операция завершилась, а страница оформления открывается без ошибки.
3. Включите тему. В административной панели откройте раздел «Оформление» и включите Gin. Проверка: Drupal сообщает, что тема включена. Само включение ещё не обязательно делает её темой по умолчанию.
4. Назначьте тему административной. В настройках оформления выберите Gin для административного интерфейса и сохраните изменения. Проверка: после перезагрузки страниц панели внешний вид администратора меняется, а публичная часть сайта остаётся оформленной прежней темой.

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

Ошибки, которые чаще всего останавливают установку

Composer запущен не из корня проекта

Сообщение вроде Composer could not find a composer.json file обычно означает, что команда выполняется не в каталоге проекта. Перейдите туда, где лежит корневой composer.json, и повторите команду. Не создавайте новый файл Composer в случайной папке: так легко получить отдельный проект, не связанный с сайтом.

Версия расширения несовместима с Drupal

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

Файлы загружены вручную, но Drupal не видит расширение

Проверьте, что расширение лежит в каталоге сайта, который ожидает ваша схема установки. В Composer-шаблоне для проекта это обычно web/modules/contrib для модулей и web/themes/contrib для тем. Однако ручная загрузка в эти папки не заменяет добавление зависимости в Composer. Для Composer-проекта установите пакет через Composer, иначе обновление или развёртывание на другом сервере может удалить ручные файлы.

Модуль установлен, но не включён

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

Тема не изменила весь сайт

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

В Composer-проекте установка — это не копирование файлов. Composer отвечает за состав проекта, а Drupal — за включение модуля и выбор темы.

Что проверить после установки

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

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

Если сайт рабочий, сначала проверьте обновление на тестовой копии, а уже потом переносите изменения. Установка пакета может изменить файл блокировки Composer и повлиять на другие зависимости проекта.

Термин: зависимости

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

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

После успешной установки зафиксируйте изменения в системе контроля версий: как минимум в проекте должны оказаться обновлённые composer.json и composer.lock. Затем повторите установку на тестовом окружении по документации проекта. Для Drupal 10 и 11 сверяйте требования расширений и порядок работы с Composer в официальной документации: совместимость конкретного модуля зависит от его релиза, версии Drupal и PHP.

Смежная тема — обновление уже установленного модуля: оно требует отдельной проверки совместимости и плана отката.