Нидерландах от 390р
Для работы человекопонятных URL в MODX 3 недостаточно включить один системный параметр. CMS должна формировать адреса по псевдонимам ресурсов, а веб-сервер — передавать запросы к несуществующим физическим файлам и каталогам в index.php. Дополнительно шаблону нужен корректный base href, особенно если ресурсы имеют вложенные адреса или сайт установлен в подкаталоге.
Типичный симптом неполной настройки выглядит так: главная страница открывается, адрес с index.php?id=... работает, а запрос к /services/hosting/ возвращает 404. Иногда страницы первого уровня доступны, но вложенные ресурсы не открываются. Причиной может быть неправильный RewriteBase на Apache, неподходящий блок try_files на Nginx, отключённый use_alias_path, ошибочный базовый URL или устаревший кеш MODX.
Как MODX обрабатывает ЧПУ
Адрес вида /services/hosting/ обычно не соответствует реальному каталогу на диске. Веб-сервер сначала проверяет, существует ли запрошенный файл или каталог. Если объекта нет, запрос передаётся входному скрипту MODX примерно в таком виде: index.php?q=services/hosting/. После этого CMS сопоставляет путь с псевдонимами ресурсов и выводит нужную страницу.
На Apache перенаправление выполняет модуль перезаписи URL и правила из .htaccess. На Nginx файл .htaccess не используется: маршрутизация задаётся непосредственно в конфигурации виртуального хоста через location, try_files и правило передачи запроса в index.php. Эти варианты описаны в документации MODX для Apache и документации для Nginx.
Важно различать два пути:
- путь в файловой системе, например
/var/www/example/modx; - путь в URL, например
/или/site/.
Для RewriteBase, location и base href важен прежде всего путь в URL. Если файлы MODX находятся в каталоге /var/www/example/modx, но этот каталог назначен корнем виртуального хоста, сайт всё равно установлен в корне URL и открывается как https://example.com/. Значит, использовать в адресах /modx/ не нужно.
Что проверить перед изменениями
Сначала определите фактическое окружение сайта. Это позволит не смешать правила Apache и Nginx и не указать подкаталог там, где его нет.
- Уточните, какой веб-сервер обслуживает сайт: Apache, Nginx или связка Nginx с Apache.
- Запишите полный адрес главной страницы. Если она открывается по
https://example.com/, URL-корень равен/. Если поhttps://example.com/site/, URL-корень равен/site/. - Найдите каталог MODX, в котором расположены
index.php,ht.access,assets,managerи другие файлы установки. - Выберите существующий вложенный ресурс для проверки, например страницу с ожидаемым адресом
/catalog/category/product/. - Создайте резервную копию изменяемого файла или конфигурации.
На виртуальном хостинге обычно можно редактировать .htaccess через файловый менеджер или FTP, но нельзя изменять системную конфигурацию Nginx. Если хостинг работает только на Nginx и панель не предоставляет настройки маршрутизации, правило try_files должен добавить провайдер. Команды с административными правами в этом случае выполнять не требуется.
На VPS перед изменением виртуального хоста сохраните его конфигурацию под другим именем. Не перезаписывайте целиком рабочий блок server или VirtualHost примером из инструкции: в нём уже могут находиться настройки PHP, HTTPS, журналов, ограничений доступа и других приложений.
Настройка параметров ЧПУ в MODX 3
Откройте системные настройки MODX и найдите параметры по ключам. Для основной схемы нужны следующие значения:
friendly_urls— включено;use_alias_path— включено, если адрес должен содержать псевдонимы родительских ресурсов.
Параметр friendly_urls включает формирование дружественных адресов. Параметр use_alias_path отвечает за полный путь с родительскими псевдонимами. При включённом значении дочерний ресурс может получить URL вида /parent/child/. Если оно отключено, структура родителей в формируемом адресе не используется.
Проверьте сами ресурсы:
- у каждого ресурса должен быть непустой и ожидаемый псевдоним;
- дочерняя страница должна находиться под нужным родителем в дереве ресурсов;
- ресурс должен быть опубликован и доступен в текущем контексте;
- псевдонимы в одном и том же пути не должны создавать неоднозначность;
- фактический URL следует получать через ссылку, сформированную MODX, а не собирать вручную по заголовкам страниц.
После изменения системных настроек пока не делайте вывод по первой проверке: карта псевдонимов может оставаться в кеше. Очистка кеша будет обязательным завершающим шагом, но сначала следует настроить веб-сервер.
Настройка ЧПУ на Apache
MODX поставляется с примером правил в файле ht.access, расположенном в корневом каталоге установки. Apache не применяет его под этим именем. Файл нужно скопировать или переименовать в .htaccess. Безопаснее сначала сделать копию: исходный пример останется доступен для сравнения после обновлений или неудачного редактирования.
Если в каталоге уже существует .htaccess, не заменяйте его без проверки. Сохраните резервную копию и добавьте необходимые правила с учётом существующей конфигурации. В имеющемся файле могут быть настройки панели управления, версии PHP, защиты каталогов или перенаправления HTTPS.
Apache: MODX в корне сайта
Если главная страница открывается непосредственно по адресу домена, базовые правила ЧПУ выглядят так:
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]RewriteEngine On включает механизм обработки правил в текущем контексте. Директива RewriteBase / указывает, что установка доступна из корня URL. Условия !-f и !-d не позволяют направлять в MODX запросы к реально существующим файлам и каталогам. Благодаря этому изображения, стили, JavaScript и содержимое assets обслуживаются напрямую.
Правило RewriteRule передаёт оставшуюся часть пути параметром q в index.php. Флаг QSA сохраняет исходные параметры запроса. Например, параметры фильтра после знака вопроса не должны исчезнуть при внутреннем перенаправлении.
Apache: MODX доступен в подкаталоге
Если сайт открывается по адресу https://example.com/site/, файл .htaccess рекомендуется держать в каталоге самой установки MODX, рядом с её index.php. Для этого примера измените базу:
RewriteEngine On
RewriteBase /site/
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php?q=$1 [L,QSA]В RewriteBase указывается URL-подкаталог, а не полный путь на диске и не доменное имя. Начальный и конечный слеши важны: для рассматриваемой установки корректно /site/, а не site, /var/www/site или полный адрес сайта. Документация MODX отдельно указывает, что для установки в подкаталоге значение RewriteBase нужно изменить соответствующим образом.
Не добавляйте имя физического каталога, если оно отсутствует в публичном URL. Например, при DocumentRoot /var/www/example/modx сайт может открываться из корня домена. В таком окружении правильным останется RewriteBase /.
Если Apache игнорирует .htaccess
Если после создания файла ничего не изменилось, проверьте следующие причины:
- файл действительно называется
.htaccess, а не.htaccess.txt; - он расположен в каталоге публичной установки MODX;
- файловый менеджер показывает скрытые файлы;
- веб-сервером является Apache либо запросы передаются от Nginx к Apache;
- на сервере разрешено применение правил перезаписи из
.htaccess; - вы редактируете конфигурацию того домена и каталога, которые обслуживают проверяемый сайт.
На виртуальном хостинге возможность использовать .htaccess определяет провайдер. Если правила игнорируются, передайте в поддержку адрес сайта, путь к файлу и пример неработающего URL. На VPS разрешение обработки .htaccess настраивается в конфигурации Apache. После изменения серверной конфигурации сначала выполните штатную проверку синтаксиса, а затем примените её безопасной перезагрузкой службы.
Ошибка 500 сразу после редактирования обычно означает, что Apache не принимает одну из директив или файл содержит синтаксическую ошибку. В таком случае восстановите резервную копию .htaccess, убедитесь, что сайт снова доступен, и добавляйте правила небольшими блоками. Причину следует искать в журнале ошибок Apache или журнале сайта в панели управления.
Если правила требуется перенести из .htaccess в конфигурацию виртуального хоста, учитывайте различия контекстов директив. Подробнее о таком переносе читайте в статье Apache без .htaccess: перенос правил в vhost.
Настройка ЧПУ на Nginx
Nginx не читает .htaccess, поэтому переименование ht.access на таком сервере само по себе ничего не изменит. Правило нужно добавить в активный блок server нужного домена. На виртуальном хостинге без доступа к конфигурации это задача технической поддержки или предусмотренного панелью редактора дополнительных директив.
Nginx: MODX в корне сайта
Внутри существующего блока server маршрутизацию MODX можно организовать через именованный location:
location @modx-rewrite {
rewrite ^/(.*)$ /index.php?q=$1&$args last;
}
location / {
try_files $uri $uri/ @modx-rewrite;
}Директива try_files последовательно проверяет файл по запрошенному URI, затем каталог, а при их отсутствии передаёт обработку в @modx-rewrite. Именованный блок преобразует путь в запрос к /index.php с параметром q. Такая схема приведена в документации MODX для Nginx.
Этот фрагмент не заменяет настройку PHP-FPM. В рабочем виртуальном хосте уже должен существовать корректный обработчик PHP, согласованный с окружением сервера. Не копируйте без проверки чужой адрес сокета или TCP-порт PHP-FPM: способ подключения зависит от установленной конфигурации.
Если в блоке server уже имеется location /, нельзя добавить второй такой же блок рядом. Внесите try_files в существующий location /, сохранив необходимые директивы. Дублирующиеся или конфликтующие location могут привести к ошибке проверки конфигурации либо к обработке запросов не тем правилом.
Nginx: MODX в URL-подкаталоге
Для сайта, который действительно открывается по адресу https://example.com/site/, правило должно учитывать префикс /site/:
location @modx-site-rewrite {
rewrite ^/site/(.*)$ /site/index.php?q=$1&$args last;
}
location /site/ {
try_files $uri $uri/ @modx-site-rewrite;
}Здесь первая часть пути /site/ удаляется из значения, передаваемого параметром q. Запрос /site/catalog/product/ будет внутренне направлен к /site/index.php?q=catalog/product/. При этом реальные файлы внутри /site/assets/ продолжат обслуживаться напрямую.
Этот пример подходит, когда корень Nginx указывает на каталог, содержащий подкаталог site. Если же директива root уже указывает непосредственно на файловый каталог MODX, а установка доступна по корню домена, используйте вариант location / без префикса.
Безопасное применение конфигурации Nginx
После редактирования сначала проверьте синтаксис:
nginx -tКоманду выполняют с правами, предусмотренными конфигурацией сервера. Если проверка сообщает об ошибке, не перезагружайте Nginx: исправьте указанную строку или восстановите резервную копию. Если тест успешен, примените конфигурацию штатной командой перезагрузки Nginx либо через панель управления. Конкретная команда управления службой зависит от операционной системы и способа установки.
После применения убедитесь, что открываются не только страницы MODX, но и реальные файлы: CSS, изображения, JavaScript, файлы из assets. Если все запросы начали попадать в CMS, вероятно, из try_files удалена проверка $uri либо правило добавлено не в тот блок.
Для самостоятельного изменения конфигурации Nginx и виртуального хоста потребуется административный доступ. Подходящий вариант для таких задач — VPS-сервер.
Россия
Нидерланды
Добавление base href в шаблон
В секции head каждого используемого HTML-шаблона добавьте базовый адрес:
<base href="https://fastfox.pro/" />MODX рекомендует этот тег, чтобы относительные ссылки отсчитывались от корня сайта, а не от адреса текущего ресурса.
Без base href браузер может неверно разрешать относительные пути на вложенной странице. Например, ссылка assets/css/main.css на странице /services/hosting/ может интерпретироваться как /services/hosting/assets/css/main.css. Аналогичная проблема возникает с относительной ссылкой contacts/: браузер способен открыть /services/hosting/contacts/, хотя требуемая страница находится по адресу /contacts/.
Сам base href не исправляет серверное правило перезаписи. Если правильный адрес, введённый вручную, возвращает 404, проверять нужно Apache, Nginx или сопоставление ресурса в MODX. Тег помогает в ситуации, когда ссылка в HTML ведёт на ошибочно составленный вложенный путь или на странице пропадают стили и изображения.
После добавления тега откройте исходный HTML страницы в браузере и посмотрите его итоговое значение. Для сайта в корне ожидается адрес наподобие https://example.com/, а для установки в URL-подкаталоге — https://example.com/site/. Конечный слеш важен для корректного разрешения относительных путей.
Если MODX выводит в base href корень домена, хотя сайт доступен только из подкаталога, проверьте значение site_url в соответствующем контексте и конфигурацию установки. Не маскируйте несогласованность случайным добавлением /site/ в каждую ссылку шаблона.
Очистка кеша и последовательная проверка
После изменения friendly_urls, use_alias_path, псевдонимов, шаблона или расположения ресурсов очистите кеш сайта штатным действием в панели MODX. Это обновит связанные с маршрутами и ресурсами кешированные данные. Очистка кеша входит в обязательную последовательность настройки ЧПУ, указанную в документации MODX.
Затем проверьте сайт в таком порядке:
- Откройте главную страницу.
- Откройте реальный статический файл, например существующее изображение из
assets. - Проверьте ресурс первого уровня, например
/contacts/. - Проверьте вложенный ресурс, например
/services/hosting/. - Добавьте к адресу тестовый параметр, если приложение его принимает, и убедитесь, что параметры запроса не теряются.
- Перейдите на заведомо несуществующий URL и убедитесь, что отображается настроенная страница ошибки MODX, а не служебная 404 веб-сервера.
Для проверки HTTP-кода из командной строки можно использовать:
curl -sS -o /dev/null -w '%{http_code}\n' https://example.com/services/hosting/Для установки в подкаталоге адрес будет выглядеть так:
curl -sS -o /dev/null -w '%{http_code}\n' https://example.com/site/services/hosting/Ожидаемый код существующей публичной страницы — обычно 200. Если настроено штатное перенаправление на вариант со слешем, HTTPS или другой канонический адрес, сначала может возвращаться код перенаправления. В таком случае проверьте конечный ответ:
curl -sS -L -o /dev/null -w '%{http_code}\n' https://example.com/services/hostingКак локализовать причину ошибки 404
Быстрее всего искать неисправность по уровню, на котором пропадает запрос: веб-сервер или MODX.
Проверка прямого запроса к index.php
Для диагностики откройте путь через параметр q:
https://example.com/index.php?q=services/hosting/Для установки в подкаталоге:
https://example.com/site/index.php?q=services/hosting/Если такой адрес открывает нужный ресурс, а обычный ЧПУ-адрес возвращает 404, MODX способен распознать путь, но веб-сервер не передаёт его в index.php. На Apache проверяйте имя и расположение .htaccess, RewriteBase и разрешение правил перезаписи. На Nginx проверяйте активный блок server, подходящий location и последовательность try_files.
Если 404 возникает и при прямом запросе с q, проблема, вероятнее всего, находится на уровне ресурса или настроек MODX. Проверьте псевдонимы, родительскую структуру, публикацию, контекст, права доступа и кеш.
Все ЧПУ возвращают 404
Когда не работает ни один дружественный адрес, наиболее вероятны следующие причины:
friendly_urlsвключён, но серверное правило отсутствует;- Apache не читает
.htaccess; - Nginx использует другой виртуальный хост или другой
location; - правило направляет запрос не к тому
index.php; - в конфигурации указан ошибочный URL-подкаталог.
Первый уровень работает, вложенные страницы возвращают 404
Если /contacts/ открывается, а /services/hosting/ — нет, проверьте:
- включён ли
use_alias_path; - совпадает ли путь с псевдонимами всех родителей;
- не изменился ли псевдоним родительского ресурса;
- нет ли реального файла или каталога, имя которого совпадает с первым сегментом URL;
- не добавляет ли относительная ссылка лишний сегмент текущего адреса;
- очищен ли кеш после перемещения ресурса или изменения псевдонима.
Условия проверки файла и каталога на Apache, а также try_files $uri $uri/ на Nginx намеренно отдают приоритет реальным объектам. Поэтому физический каталог /services/ может перехватить запрос раньше MODX. В такой ситуации изучите структуру файлов и конфигурацию этого каталога, а не удаляйте проверки существующих объектов без оценки последствий.
Страница открывается, но стили и изображения возвращают 404
Это обычно указывает не на маршрутизацию ресурса, а на относительные URL в HTML. Проверьте итоговый base href и адреса проблемных файлов в инструментах разработчика браузера. Если вместо /assets/css/main.css запрашивается /parent/child/assets/css/main.css, исправьте базовый адрес или сами ссылки.
После настройки появилась ошибка 500
На Apache временно восстановите предыдущий .htaccess. Если сайт заработал, сравните файлы и верните только минимальный блок ЧПУ. Не оставляйте сайт с ошибкой, продолжая менять правила вслепую.
На Nginx не применяйте конфигурацию, если nginx -t завершился ошибкой. Сообщение обычно содержит имя файла и номер строки. Исправьте дублирующийся location, пропущенную скобку или неверно размещённую директиву, снова выполните тест и только затем перезагрузите службу.
После очистки кеша результат не изменился
Убедитесь, что проверяете правильный домен и контекст, а изменения внесены в активный шаблон и конфигурацию обслуживающего виртуального хоста. При наличии внешнего прокси или кеширующего слоя ответ может временно приходить не с того уровня, который вы только что изменили. Сравните результат в браузере и через curl, а также изучите журналы доступа веб-сервера.
Итоговый контрольный список
- В MODX включён параметр
friendly_urls. - Для адресов с родительскими псевдонимами включён
use_alias_path. - У ресурсов заполнены правильные псевдонимы, а сами ресурсы опубликованы.
- На Apache файл
ht.accessскопирован или переименован в.htaccess. - Для сайта в корне Apache использует
RewriteBase /. - Для сайта по адресу
/site/Apache используетRewriteBase /site/. - На Nginx отсутствующие файлы и каталоги передаются в правило MODX через
try_files. - Префикс подкаталога одинаково учтён в
location, правилеrewriteи пути кindex.php. - В шаблоне присутствует
<base href="https://fastfox.pro/" />, а его итоговое значение соответствует публичному адресу установки. - После изменений очищен кеш MODX.
- Проверены главная страница, статический файл, ресурс первого уровня, вложенный ресурс и несуществующий адрес.
Если прямой запрос через index.php?q=... работает, сосредоточьтесь на правилах веб-сервера. Если он тоже возвращает 404, проверяйте структуру и настройки ресурсов MODX. Такое разделение позволяет быстро определить источник ошибки и не менять одновременно шаблон, CMS и конфигурацию сервера.
