Композит (Static HTML Cache) — технология, которая разделяет страницу на «быструю» статическую оболочку и отложенные динамические фрагменты. Браузер получает готовый HTML-файл практически мгновенно, а динамика догружается AJAX-ом уже после первого рендера. В результате метрики TTFB/FP/Core Web Vitals улучшаются в разы.
1. Как это работает
Первый визит
- ядро собирает страницу как обычно;
- отмеченные динамические зоны вырезаются;
- в конец добавляется JS-загрузчик
frameCache; - итоговый HTML сохраняется в
/bitrix/html_pages/....
Повторный визит
- Nginx/Apache отдаёт файл с диска за ≈20 мс;
- параллельно JS делает AJAX-запрос
/bitrix/tools/composite_data.php, подменяя заглушки свежим HTML.
Заголовок X-Bitrix-Composite: Cache/NCC подсказывает, откуда пришла страница (кэш или генерация).
2. Режимы работы
| Режим | Когда использовать | Что делает |
|---|---|---|
| Автокомпозит | «Коробка», лендинги, сайты без кастомных шаблонов | Система сама помечает все компоненты как динамические; нужно лишь нажать «Включить». |
| Ручной композит | Интернет-магазины, порталы с кастомным JS | Разработчик сам определяет границы динамики, TTL и заглушки. |
3. Включение технологии
- Админ-панель → Настройки → Настройки продукта → Композитный сайт.
- Выберите режим и нажмите «Включить».
- Настройте:
- список доменов;
- параметры URL, игнорируемые при формировании ключа кэша (например,
utm_*); - тип хранилища (
files,memcached,APCu).
После переключения режима обязательно очистите общий и компонентный кэш.
4. Разметка динамических зон
4.1. Внутри шаблона компонента
<?php
$frame = $this->createFrame()->begin(); // начало динамики
?>
<span id="cart-count"><?=$arResult['COUNT']?></span>
<?php
$frame->beginStub(); // заглушка
?>
<span id="cart-count">0</span>
<?php
$frame->end(); // конец динамики
?>Метод createFrame() доступен в любом шаблоне компонента Bitrix Framework.
4.2. Вне компонента (шапка, футер)
use Bitrix\Main\Page\Frame;
Frame::getInstance()->startDynamicWithID('header-auth');
// ... любой PHP/HTML с авторизацией ...
Frame::getInstance()->finishDynamicWithID('header-auth', '');4.3. Дополнительные возможности
$frame = Bitrix\Main\Page\Frame::getInstance();
$frame->setAutoUpdate(false); // отключить AJAX-обновление, кэш только по TTL
$frame->setAutoUpdateTTL(120); // TTL файла-кэша 2 мин4.4. Если компонент подключает ресурсы <head>
use Bitrix\Main\Page\{FrameStatic, AssetMode};
$area = new FrameStatic('workarea');
$area->setAssetMode(AssetMode::STANDARD);
$area->setStub('<!-- stub -->');
$area->startDynamicArea();
$APPLICATION->IncludeComponent('my:comp', '.default', []);
$area->finishDynamicArea();5. Клиентские события frameCache
function initCounters() {
// ваш код
}
if (window.frameCacheVars) { // страница из кэша
BX.addCustomEvent('onFrameDataReceived', initCounters);
} else {
BX.ready(initCounters); // обычная загрузка
}onFrameDataReceivedBefore— до вставки всех блоков;onBeforeDynamicBlockUpdate— перед заменой каждого блока;onFrameDataReceived— после полной подмены.
6. Управление кэшем
- Очистить все HTML-файлы:
\Bitrix\Main\Data\StaticHtmlCache::getInstance()->deleteAll(); - Плановая очистка кроном:
/bitrix/modules/main/tools/cron_html_pages.php. - Временно отключить композит для URL: добавить
?ncc=1или вызвать$APPLICATION->SetPageProperty('ncc', 'y');.
7. Частые ошибки и решения
| Симптом | Причина | Исправление |
|---|---|---|
| Страница каждый раз пересохраняется | Случайные rand(), уникальные ID в HTML |
Перенесите уникальные фрагменты в динамическую зону |
| «Прыжок» блока при подмене | Высота заглушки ≠ высоте контента | Задайте фиксированную высоту или CSS-анимацию |
| Не работает в IE ≤ 9 | Ограничение по поддержке postMessage |
Для старых браузеров композит автоматически отключён |
| Цифра корзины «моргает» | AJAX успевает позже визуала | Храните значение в BX.localStorage и показывайте сразу |
8. Ограничения по пользователям
Для гостей ставится cookie _CC; для групп, исключённых из композита, — _NCC. Так можно кешировать только анонимный трафик, оставив персональные разделы (корзина, кабинет) динамичными.
9. Инструменты разработчика
- Chrome расширение “Bitrix Composite” — подсвечивает состояние кэша и объясняет причину его сброса.
- Панель «Статистика и отладка» в админке → вкладка «Скорость сайта».
- Заголовок
X-Bitrix-Compositeв Network-панели браузера.
10. Мини-конфигурация Nginx
location / {
try_files /bitrix/html_pages/$host$uri_index@.html $uri $uri/ /index.php?$args;
}
location ~* @\.html$ {
add_header X-Bitrix-Composite "Cache";
expires 30m;
}(Если вы используете BitrixVM ≥ 5.1, этот блок генерируется автоматически.)
11. Когда не стоит включать композит
- Страницы, полностью зависящие от пользователя: оформление заказа, «Мой профиль», поиск.
- Контент меняется чаще, чем TTL кэша.
- Приложения, где важнее точное время полной загрузки тяжёлых JS-бандлов, а не первый рендер.
Итоги
Технология «Композитный сайт» позволяет за пару кликов (или за несколько часов ручной разметки) сократить время первого отображения страницы до десятков миллисекунд, улучшить Core Web Vitals и конверсию. Используйте примеры из этого справочника, контролируйте заголовки и панель отладки — и ваш Bitrix-проект будет «летать», оставаясь динамичным там, где это действительно нужно.