Настройка дружественных URL в MODX: пошаговая инструкция

За 15–30 минут вы сможете заменить адрес вида index.php?id=12 на короткий URL вроде /catalog/telefon/. Инструкция рассчитана на MODX Revolution 2.8.x и 3.x, сайт на Apache и пользователя с доступом в админку и к файлам проекта.

Что подготовить до начала

• Версию MODX: её можно посмотреть в панели управления или в системной информации.
• Доступ в Manager с правами на изменение системных настроек.
• Доступ к файлам сайта через SSH, FTP или файловый менеджер хостинга.
• Резервную копию базы данных и каталога сайта.
• Понимание, находится ли сайт в корне домена или в подпапке, например /shop/.

Если сайт работает на Nginx, файл .htaccess не используется. В этом случае правила перенаправления на MODX настраиваются в конфигурации Nginx, обычно с участием администратора сервера. Ниже разобран вариант с Apache.

Сноска. Алиас — короткое имя ресурса, которое MODX использует в URL вместо числового идентификатора или заголовка страницы.

Шаг 1. Включите дружественные URL в MODX

Откройте в Manager раздел системных настроек. В MODX Revolution 2 и 3 названия пунктов могут немного отличаться, но искать их нужно по ключам friendly_urls и automatic_alias.

1. Найдите настройку friendly_urls и включите её.
2. Проверьте настройку automatic_alias. Включите её, если хотите, чтобы MODX создавал алиас из заголовка ресурса автоматически.
3. Оставьте suffix пустым, если нужны адреса с завершающим слешем или без расширения. Не добавляйте туда .html без необходимости: смена формата позже создаст новые адреса и потребует перенаправлений.
4. Настройку use_alias_path сначала оставьте выключенной. Она нужна для построения URL из цепочки вложенных ресурсов, но усложняет перенос страниц и изменение структуры сайта.
5. Сохраните настройки.

Проверка: при повторном открытии страницы настроек у friendly_urls стоит значение Да, а изменения не сбрасываются после обновления.

Шаг 2. Подготовьте файл .htaccess

MODX получает запросы к несуществующим файлам через фронт-контроллер — обычно это index.php. Apache должен передать ему запрос /catalog/telefon/, иначе сервер вернёт 404 ещё до запуска MODX.

1. Откройте корневой каталог сайта. Это папка, где находятся index.php, core, manager и каталог с публичными файлами.
2. Найдите поставляемый с MODX файл ht.access.
3. Сделайте копию текущего файла конфигурации веб-сервера, если он уже существует.
4. Переименуйте ht.access в .htaccess. Точка в начале имени обязательна.
5. Если сайт установлен в подпапку, проверьте значение RewriteBase в файле. Для адреса https://example.org/shop/ базовый путь должен соответствовать /shop/, а не корню домена.

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

Проверка: файл виден в каталоге сайта именно как .htaccess, а не как .htaccess.txt. В панели хостинга включите показ скрытых файлов.

Дружественный URL — это не только настройка MODX. Нужны одновременно корректный алиас, включённая маршрутизация и правило веб-сервера. Если сломался любой из трёх элементов, страница не откроется.

Шаг 3. Проверьте алиасы ресурсов

Откройте нужный ресурс в дереве сайта и перейдите к его полям. У ресурса должны быть опубликованный статус, корректный алиас и родитель, если страница вложенная.

1. Введите алиас латинскими буквами, цифрами и дефисами, например telefon или oplata-i-dostavka.
2. Не используйте пробелы, слеши, знак вопроса и символы, которые имеют специальное значение в URL.
3. Убедитесь, что в пределах одного родителя нет двух ресурсов с одинаковым алиасом.
4. Сохраните ресурс и очистите кеш MODX через соответствующий пункт Manager.

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

Шаг 4. Настройте вложенные адреса при необходимости

По умолчанию MODX может использовать алиас ресурса без всей цепочки родителей. Если нужен адрес /catalog/telefon/, а не только /telefon/, включите use_alias_path.

1. Создайте или проверьте структуру: «Каталог» с алиасом catalog и дочерняя страница «Телефон» с алиасом telefon.
2. Включите use_alias_path в системных настройках.
3. Сохраните настройки и очистите кеш.
4. Откройте родительскую и дочернюю страницы. Проверьте ссылки из меню и шаблонов, а не только прямой ввод адреса.

Проверка: дочерний ресурс открывается по полному пути, а ссылки на него не ведут на старый адрес. Инвалидация старых URL и настройка 301-редиректов — отдельная задача, здесь рассматривается только построение адресов.

Шаг 5. Проверьте результат

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

Успешный результат: адрес не содержит index.php и параметра id, сервер не возвращает 404, а страница загружается вместе со стилями и скриптами.

Если не получилось

Страница возвращает 404

Чаще всего Apache не читает .htaccess, файл лежит не в корне сайта или сайт установлен в подпапке с неверным RewriteBase. Проверьте, что на сервере разрешено использование правил каталога, а модуль переписывания URL включён.

Появилась ошибка 500

Причина обычно в синтаксисе .htaccess или в директиве, запрещённой настройками хостинга. Временно верните резервную копию файла и посмотрите журнал ошибок Apache. Не добавляйте правила по одному из случайных инструкций: сначала восстановите штатный файл версии MODX.

В адресе всё ещё есть index.php

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

URL открывается, но CSS и изображения пропали

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

Две страницы ведут на один адрес

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

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

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