Как настроить D7-роутинг в 1С-Битрикс: local/routes/web.php?

Вы прописали маршрут в /local/routes/api.php, добавили секцию routing в .settings.php, открываете /api/v1/ping в браузере – и снова 404. В логах nginx запрос уходит в старый urlrewrite.php, хотя PHP-код выглядит правильно. D7-роутинг в 1С-Битрикс: Управление сайтом – это отдельная цепочка: веб-сервер должен сначала отдать запрос в routing_index.php, затем ядро подключит файлы из /local/routes/. Ниже – пошаговое включение от Apache или nginx до первого ответа контроллера без поломки ЧПУ-каталога.

D7 Routing связывает URL с PHP-кодом напрямую, без физической страницы в папке сайта. Минимум для старта: модуль main версии 21.400 и выше, переключение rewrite на /bitrix/routing_index.php, секция routing в .settings.php и файл /local/routes/web.php. ЧПУ-страницы каталога оставляйте на urlrewrite.php – для API и модульных endpoint используйте префикс /api.

Речь про коробочную CMS "1С-Битрикс: Управление сайтом", а не про облачный Bitrix24. В портале CRM свои механизмы маршрутизации – они здесь не рассматриваются.

Роутинг – это "диспетчер адресов": он смотрит на URL и решает, какой PHP-код его обработает. Это не ЧПУ для каталога. Новый API-адрес лучше вынести в D7-маршруты – иначе nginx ищет папку /api/v1/ на диске и отдаёт 404.

Выберите, когда нужен D7 Routing, а когда urlrewrite

Перед правками сервера определите задачу. D7 Routing нужен, когда URL должен вести в контроллер или замыкание без страницы в структуре сайта: REST-подобный API, webhook, JSON для мобильного приложения, endpoint модуля. Для витрины, новостей и каталога с ЧПУ по-прежнему работает urlrewrite.php – подробный разбор в материале про ЧПУ и urlrewrite в Битрикс.

Делайте: держите API под префиксом /api или /api/v1, чтобы не пересечься с ЧПУ. Не делайте: не комментируйте весь блок urlrewrite в .htaccess – каталог перестанет открываться. Для точечной миграции старых правил вендор предлагает PublicPageController, но для нового кода берите Engine\Controller.

Включите routing_index.php на Apache и nginx

Главная причина 404 при "правильном" web.php – веб-сервер не передаёт запрос в роутер. На Apache в корневом .htaccess правило должно вести на /bitrix/routing_index.php, а не только на urlrewrite.php. На nginx – директива try_files с тем же файлом.

Цепочка запроса:
Браузер → веб-сервер (Apache/nginx) → routing_index.php → ядро Битрикс → файл из /local/routes/ → контроллер или замыкание → ответ

Типичная ошибка: на staging с Apache маршрут есть, на prod с nginx забыли конфиг – запрос уходит в urlrewrite.php. Сравните окружения до выкладки.

1. Apache: в .htaccess найдите блок rewrite и убедитесь, что есть правило на /bitrix/routing_index.php (по документации для вашей версии ядра).
2. nginx: в server-блоке добавьте try_files $uri $uri/ /bitrix/routing_index.php?$args; для location с PHP.
3. Проверка: откройте тестовый URL и в DevTools посмотрите, что ответ пришёл через роутер, а не 404 от nginx.
4. Статика: не направляйте CSS, JS и картинки через routing_index.php – для них оставьте прямую отдачу файлов.
5. Staging = prod: прогоните один и тот же GET на обоих серверах до релиза.

Делайте: сохраните резервную копию .htaccess или nginx-конфига перед правкой. Не делайте: не удаляйте правила для urlrewrite.php – они нужны ЧПУ-страницам параллельно с роутингом.

Настройте секцию routing в .settings.php

Файлы маршрутов лежат в /local/routes/, но ядро подключит их только если в .settings.php (в /bitrix/ или /local/) есть секция routing. По умолчанию часто указан только web.php. Если вы создали api.php – добавьте его в массив config явно.

'routing' => [
    'value' => [
        'config' => ['web.php', 'api.php'],
    ],
    'readonly' => true,
],

Нюанс из документации: если есть и /local/routes/web.php, и /bitrix/routes/web.php, подключатся оба – local не перекрывает bitrix полностью. Свои маршруты держите в /local/routes/.

Делайте: перечислите в config все используемые файлы (web.php, api.php). Не делайте: не кладите маршруты в /bitrix/routes/ на проде – обновление ядра может затереть кастом.

Создайте первый маршрут в /local/routes/web.php

Файл /local/routes/web.php получает объект RoutingConfigurator (сокращённо – "конфигуратор маршрутов"). В нём вы описываете, какой URL на какой код ссылается. Начните с простого ping-endpoint, затем группируйте API.

<?php
use Bitrix\Main\Routing\RoutingConfigurator;

return function (RoutingConfigurator $routes) {
    $routes->get('/api/v1/ping', function () {
        return new \Bitrix\Main\Engine\Response\Json(['status' => 'ok']);
    });

    $routes->prefix('api/v1')->group(function (RoutingConfigurator $routes) {
        $routes->get('orders/{id}', function ($id) {
            return new \Bitrix\Main\Engine\Response\Json(['order_id' => (int)$id]);
        });
    });
};

Параметр {id} – переменная из URL. Методы get, post, any ограничивают HTTP-глагол. prefix добавляет общий префикс группе маршрутов.

Делайте: тестируйте сначала замыкание (closure), потом переносите логику в контроллер. Не делайте: не дублируйте один URL в web.php и urlrewrite.php – победит то правило, которое сработает раньше, и отладка усложнится.

Привяжите маршрут к Engine\Controller модуля

Когда ping работает, подключите класс контроллера из своего модуля. Если модуля ещё нет – сначала создайте каркас по гайду как создать свой модуль на Битрикс. Контроллер наследует \Bitrix\Main\Engine\Controller, а маршрут ссылается на него массивом [Класс::class, 'имяAction'].

$routes->get('/api/v1/orders', [
    \Vendor\Myshop\Controller\Api\Order::class,
    'listAction',
]);

Фильтры доступа (configureActions, prefilters) настраиваются внутри контроллера – это зона D7 Engine\Controller и AJAX. Для вызовов с уже открытой страницы через BX.ajax.runAction отдельный URL не нужен. Если нужен внешний REST с токенами и OAuth – смотрите настройку REST API модуля: это другой механизм, не D7 Routing.

Делайте: именуйте action-методы с суффиксом Action (listAction, getAction). Не делайте: не смешивайте в одном контроллере публичный API и админские методы без prefilters – откроете лишние данные.

Разберите типичные 404 и проверьте результат

Если после всех правок URL всё ещё не открывается, пройдите диагностику по трём уровням: веб-сервер, конфиг ядра, сам файл маршрута.

Чек-лист перед закрытием задачи:

1. GET /api/v1/ping возвращает JSON без 404.
2. ЧПУ-страница каталога открывается как раньше.
3. В .settings.php перечислены все файлы из /local/routes/.
4. На staging и prod одинаковые правила rewrite.
5. Секреты и токены не лежат в web.php – только в настройках модуля.

Результат: у вас работает отдельное URL-пространство для API, каталог на ЧПУ не сломан, а новые endpoint добавляются строкой в web.php или api.php без правки urlrewrite.php. С версии main 23.500.0 для генерации ссылок по имени маршрута доступен \Bitrix\Main\Application::getRouter().

Если нужна помощь с внедрением API-слоя на действующем магазине – напишите нам, разберём архитектуру до правок на prod. Похожие кейсы смотрите в портфолио.

Автор: Максим Мольков, разработчик 1С-Битрикс.
Источники: документация BitrixFramework – Роутинг, курс разработчика – глава "Роутинг", практика внедрений на CMS.

Частые вопросы