Как добавить скрипт в 1С-Битрикс: пошаговая инструкция 2026

Добавление скриптов в 1С-Битрикс — задача, с которой рано или поздно сталкивается каждый разработчик или администратор сайта.hether вы хотите подключить Google Analytics, кастомный JavaScript-плагин или оптимизировать загрузку CSS-стилей, важно делать это правильно, чтобы не сломать функциональность сайта и не потерять в производительности. В этой статье мы разберём все актуальные способы интеграции скриптов — от простых до продвинутых, с учётом особенностей архитектуры Битрикс.

Особенность 1С-Битрикс в том, что система предлагает несколько уровней внедрения кода: через визуальный редактор, напрямую в шаблоны, через компоненты или даже на уровне ядра. Выбор метода зависит от задачи: например, для одноразовых изменений подойдёт редактор, а для глобальных правок потребуется работа с файловой структурой. Мы рассмотрим каждый вариант с практическими примерами и предупредим о типичных ошибках, которые могут привести к конфликтам с композитным кешем или дублированию скриптов.

1. Добавление скриптов через визуальный редактор (для новичков)

Самый простой способ — использовать встроенный HTML/JS-редактор в админпанели 1С-Битрикс. Он подходит для разовых вставок кода, например, счетчиков аналитики или виджетов соцсетей. Чтобы им воспользоваться:

Перейдите в Контент → Структура сайта и выберите нужную страницу.
В режиме редактирования нажмите кнопку HTML (или Исходный код в визуальном редакторе).
Вставьте свой скрипт между тегами <head> или перед закрывающим </body>.

⚠️ Внимание: Этот метод имеет ограничения. Код, добавленный таким образом, будет виден только на конкретной странице. Кроме того, при обновлении шаблона или сбросе кеша изменения могут пропасть. Для глобальных скриптов (например, jQuery или Google Tag Manager) лучше использовать другие способы.

2. Подключение через шаблоны сайта (рекомендуемый способ)

Для стабильной работы скриптов на всех страницах сайта необходимо редактировать шаблоны. В 1С-Битрикс за это отвечают файлы header.php и footer.php, расположенные в папке шаблона (обычно /bitrix/templates/[VAШ_ШАБЛОН]/). Вот как это сделать:

Скопируйте оригинальные файлы шаблона в свою тему (если используете дочернюю тему).
Откройте header.php для скриптов в <head> или footer.php для подключения перед </body>.
Добавьте код напрямую или через функцию Asset::getInstance->addJs (рекомендуется для Битрикс).

Пример подключения jQuery через Asset API:

<?php
use Bitrix\Main\Page\Asset;
Asset::getInstance->addJs('https://code.jquery.com/jquery-3.6.0.min.js');
?>

⚠️ Внимание: При редактировании шаблонов всегда создавайте резервную копию! Ошибка в коде может привести к"белому экрану" на всём сайте. Также помните, что некоторые скрипты (например, Bootstrap) уже могут быть подключены в ядре Битрикс — проверьте это через Внешний вид → Шаблоны → Настройки шаблона.

☑️ Подготовка к редактированию шаблонов

Создать бэкап файловПроверить наличие скрипта в ядре БитриксИспользовать дочернюю темуТестировать изменения на staging-версии

Выполнено: 0 / 4

3. Использование компонента `main.include` для гибкого управления

Если вам нужно подключать скрипты динамически (например, только на определённых страницах или для конкретных пользовательских групп), удобно использовать компонент main.include. Этот метод позволяет:

📌 Подключать разные скрипты для разных разделов сайта
🔄 Управлять порядком загрузки файлов
🛡️ Избегать конфликтов с композитным кешем

Инструкция:

Создайте файл с расширением .php в папке /local/include/ (например, custom_scripts.php).
Поместите в него свой JavaScript или CSS-код, обёрнутый в PHP-теги.

В нужном месте шаблона или страницы вставьте вызов:

<?$APPLICATION->IncludeComponent(
"bitrix:main.include",
"",
Array(
"AREA_FILE_SHOW" =>"file",
"PATH" =>"/local/include/custom_scripts.php"
)
);?>

Преимущество этого метода в том, что вы можете управлять подключением скриптов через условия. Например, добавлять Facebook Pixel только на страницы корзины или LiveChat только для авторизованных пользователей.

Что будет если подключить скрипт дважды?

Дублирование скриптов может привести к ошибкам в консоли браузера (например,"Uncaught Error: Bootstrap's JavaScript requires jQuery"), увеличению времени загрузки страницы и конфликтам в работе плагинов. В Битрикс это часто происходит при одновременном подключении через шаблон и компонент.

4. Динамическое подключение через `Asset API` (для разработчиков)

Для опытных пользователей самый надёжный способ — использование встроенного Asset API. Этот метод позволяет:

🔗 Подключать скрипты с зависимостями (например, сначала jQuery, потом плагин)
📦 Упаковывать и минифицировать файлы автоматически
🚀 Оптимизировать загрузку для композитного сайта

Пример подключения кастомного скрипта с зависимостью от jQuery:

<?php
use Bitrix\Main\Page\Asset;

Asset::getInstance->addJs('/local/js/custom-script.js');
Asset::getInstance->addJs('https://cdn.jsdelivr.net/npm/slick-carousel@1.8.1/slick/slick.min.js', true);
// Параметр"true" указывает, что скрипт нужно подключить в конец <body>
?>

Для CSS-файлов используйте аналогичный метод addCss. Важно: если вы подключаете скрипты через Asset API в компоненте, убедитесь, что вызов происходит в методе executeComponent или onPrepareComponentParams, иначе файлы могут не подгрузиться.

💡

Для отладки подключённых скриптов используйте режим"Показать включённые области" в админпанели Битрикс (Настройки → Настройки продукта → Основные настройки → Показывать включённые области). Это поможет увидеть, какие файлы подгружаются на странице и в каком порядке.

5. Подключение через `.parameters.php` (для компонентов)

Если вы разрабатываете собственный компонент или модифицируете существующий, можно управлять скриптами через файл .parameters.php. Этот метод полезен, когда:

🔧 Нужно дать администратору возможность включать/отключать скрипты через визуальный интерфейс
🎛️ Требуется гибко настраивать параметры подключения (отложенная загрузка, асинхронность)

Пример структуры .parameters.php:

<?php
$arTemplateParameters = array(
"USE_CUSTOM_SCRIPT" => array(
"NAME" =>"Подключать кастомный скрипт",
"TYPE" =>"CHECKBOX",
"DEFAULT" =>"N",
),
"SCRIPT_ASYNC" => array(
"NAME" =>"Загружать скрипт асинхронно",
"TYPE" =>"CHECKBOX",
"DEFAULT" =>"Y",
"PARENT" =>"USE_CUSTOM_SCRIPT",
)
);
?>

Затем в component_epilog.php добавьте логику подключения:

<?php
if ($arParams["USE_CUSTOM_SCRIPT"] =="Y") {
$async = ($arParams["SCRIPT_ASYNC"] =="Y")?'async="async"':'';
Asset::getInstance->addString(<<<HTML
<script {$async} src="/local/js/custom.js"></script>
HTML
);
}
?>

⚠️ Внимание: При использовании этого метода учитывайте, что изменения в .parameters.php требуют очистки кеша компонента. В противном случае новые параметры могут не отобразиться в админпанели.

6. Работа со скриптами в композитном режиме

Если ваш сайт работает в композитном режиме (включается в Настройки → Производительность → Композитный сайт), стандартные методы подключения скриптов могут не сработать. Это связано с тем, что Битрикс агрегирует и кеширует все статичные файлы. Чтобы ваши скрипты корректно подгружались:

Проблема	Решение	Пример кода
Скрипты не подгружаются	Используйте `BX.addCustomEvent` для динамической загрузки	`BX.addCustomEvent("onAjaxSuccess", function{ / ваш код / };`
Конфликт версий библиотек	Подключайте скрипты через `Asset::getInstance->addJs` с приоритетом	`Asset::getInstance->addJs(..., ['priority' => 100])`
CSS не применяется	Добавьте стили через `Asset::getInstance->addString` с обёрткой в <style>	`Asset::getInstance->addString('<style>.class { color: red; }</style>')`

Для отладки композитного режима включите показ служебной информации в настройках производительности. Это поможет увидеть, какие файлы были объединены и минифицированы, а какие — нет.

💡

В композитном режиме избегайте подключения скриптов через тег <script> напрямую в шаблоне. Используйте только Asset API или динамическую загрузку через JavaScript-events.

7. Типичные ошибки и как их избежать

Даже опытные разработчики иногда сталкиваются с проблемами при добавлении скриптов в Битрикс. Вот самые распространённые ошибки и способы их решения:

🚫 Дублирование скриптов: Происходит при подключении одного и того же файла через шаблон и компонент. Проверяйте подключённые файлы через Внешний вид → Шаблоны → Просмотр включённых областей.
🐢 Медленная загрузка: Скрипты блокируют рендеринг страницы. Решение — использовать атрибуты async или defer, либо подключать скрипты в конце <body>.
🔄 Конфликт версий: Например, две разные версии jQuery. Используйте BX.loadExt для загрузки библиотек из ядра Битрикс.
📱 Не работает на мобильных: Проверьте, не блокирует ли адблокер ваш скрипт (особенно актуально для аналитики). Тестируйте на реальных устройствах, а не только в эмуляторе.

Если после добавления скрипта сайт перестал работать, проверьте:

Логи PHP (/bitrix/modules/main/include/prolog_admin_after.php)
Консоль браузера (F12 → Console)
Настройки прав доступа к файлам (должны быть 644 для файлов и 755 для папок)

💡

Для отладки JavaScript в Битрикс используйте расширение"Bitrix Debug Panel" для Chrome. Оно показывает все подключённые скрипты, события и ошибки в удобном виде.

FAQ: Ответы на частые вопросы

Как подключить Google Tag Manager в Битрикс?

Лучше всего использовать Asset API в файле footer.php вашего шаблона:

Asset::getInstance->addString('
<!-- Google Tag Manager -->
<script>
(function(w,d,s,l,i){w[l]=w[l]||;w[l].push({"gtm.start":
new Date.getTime,event:"gtm.js"});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!="dataLayer"?"&l="+l:"";j.async=true;j.src=
"https://www.googletagmanager.com/gtm.js?id="+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,"script","dataLayer","GTM-XXXXXX");
</script>
<!-- End Google Tag Manager -->
', true);

Не забудьте заменить GTM-XXXXXX на ваш идентификатор.

Почему мой скрипт не работает в композитном режиме?

В композитном режиме Битрикс объединяет и минифицирует все статичные файлы. Если ваш скрипт зависит от динамически подгружаемых данных, используйте:

BX.ready(function {
// Ваш код здесь
BX.ajax.runComponentAction('namespace:component','action', {
data: { key:'value' }
}).then(function(response) {
console.log(response.data);
});
});

Как подключить скрипт только на главной странице?

Используйте условие в шаблоне:

<?php
if ($APPLICATION->GetCurPage(false) === SITE_DIR) {
Asset::getInstance->addJs('/local/js/mainpage-only.js');
}
?>

Или через компонент main.include с настройкой видимости в параметрах компонента.

Можно ли подключить скрипт из CDN?

Да, но рекомендуется:

Использовать Asset::getInstance->addJs с полным URL.
Добавлять локальный фоллбек на случай недоступности CDN:

<script src="https://cdn.example.com/script.js"></script>
<script>
if (!window.YourLibrary) {
document.write('<script src="/local/js/fallback.js"><\/script>');
}
</script>

Как отключить стандартный jQuery в Битрикс и подключить свою версию?

Отключить встроенный jQuery можно через init.php:

<?php
$GLOBALS['APPLICATION']->SetAdditionalCSS(SITE_TEMPLATE_PATH.'/css/no-jquery.css', true);
$GLOBALS['APPLICATION']->AddHeadScript(SITE_TEMPLATE_PATH.'/js/jquery-3.6.0.min.js');
?>

Но помните: многие модули Битрикс зависят от стандартной версии jQuery 1.12.4. Отключение может сломать функциональность админпанели.

Как правильно добавить скрипт в 1С-Битрикс: 5 проверенных способов

1. Добавление скриптов через визуальный редактор (для новичков)

2. Подключение через шаблоны сайта (рекомендуемый способ)

☑️ Подготовка к редактированию шаблонов

3. Использование компонента main.include для гибкого управления

4. Динамическое подключение через Asset API (для разработчиков)

5. Подключение через .parameters.php (для компонентов)