Как обновить модуль Битрикс: через админку, Marketplace и вручную

Коротко: три способа обновить модуль Битрикс

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

Первый — штатный механизм системы обновлений. Работает через закладку «Установка обновлений» в админке и тянет рекомендуемые обновления модулей прямо с серверов 1С-Битрикс. Это основной путь для модулей из коробки: main, iblock, sale, catalog. Второй — Marketplace, страница «Сторонние обновления» (Marketplace > Обновления решений). Здесь обновляются модули партнёров, и в контекстной панели есть отдельная кнопка «Проверить обновления». Третий — ручная установка архива, когда штатный способ не срабатывает или модуль вообще не зарегистрирован в системе обновлений.

Какой выбирать — зависит от того, откуда пришёл модуль. Разберём каждый способ отдельно, а пока зафиксируем три точки входа:

• Через админку — закладка «Установка обновлений», для модулей из коробки и стандартных обновлений продукта.
• Через Marketplace — Marketplace > Обновления решений, для сторонних модулей партнёров 1С-Битрикс.
• Вручную — установка архива модуля, когда автоматика недоступна или модуль не подписан на обновления.

Как обновить модуль Битрикс через админку

Штатный механизм обновлений в админке не «один из вариантов», а единственный корректный путь для всего, что входит в состав продукта. Речь про модули ядра (main, iblock, sale, catalog), языковые файлы интерфейса и обновления самой системы обновлений. Когда мы разбираем инциденты после «ручных» апдейтов, в девяти случаях из десяти причина одна: файлы модуля подменили из архива, но не прошли по цепочке миграций, которые Bitrix выполняет при штатной установке. Таблицы в базе остаются старой структуры, а код уже рассчитывает на новые поля.

Через админку обновление проходит контролируемо: система сама определяет, какие модули требуют свежих версий, сама тянет только разницу между релизами и сама применяет скрипты миграции. Для проектов с активным импортом или интеграциями это критично. Рассинхрон версий между iblock и catalog вылезает не сразу, а через неделю странными ошибками на боевом сайте.

Ниже — последовательность, которой мы пользуемся сами.

1. Открыть раздел обновлений системы и убедиться, что продукт зарегистрирован. На закладке «Установка обновлений» отображается информация о регистрации — если её нет, обновления модулей не подтянутся, пока не введёте лицензионный ключ.
2. Просмотреть рекомендуемые обновления модулей и опциональные языковые файлы. Система разделяет их: рекомендуемые — это апдейты кода модулей, опциональные — языковые файлы интерфейса, их можно ставить выборочно.
3. Если среди списка есть обновление самой системы обновлений — установить его первым. Без свежего апдейтера остальные пакеты могут отработать некорректно.
4. Запустить установку выбранных обновлений и дождаться завершения. Не закрывать вкладку и не прерывать процесс — миграции выполняются в несколько проходов, а прерывание на середине оставит модуль в половинчатом состоянии.

Список обновлений читается не как «галочки на всё», а как очередь с приоритетами. Рекомендуемые обновления модулей — это то, что продукт считает нужным установить для текущей конфигурации: фиксы безопасности, совместимость с новыми версиями ядра, исправления известных багов. Их мы обычно ставим все, предварительно прогнав на тестовом стенде. Языковые файлы опциональны, потому что не влияют на логику работы модуля — это только переводы интерфейса. Если сайт одноязычный и русская локализация уже актуальна, можно их пропустить. Если в проекте есть английская или другая языковая версия — ставить обязательно, иначе часть новых полей останется без перевода.

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

Обновление модулей через Marketplace: сторонние решения

Типичный сценарий: модуль куплен у партнёра в Marketplace, поставился через установщик решений, а потом выясняется, что в админке он в списке штатных обновлений не появляется. Логично: это не модуль из состава продукта, и основной механизм обновлений его не видит. Для таких решений в Битриксе есть отдельная точка входа — страница Marketplace > Обновления решений, она же «Сторонние обновления». Именно оттуда мы и обновляем всё, что куплено у партнёров: тикет-системы, интеграции с CRM, отраслевые надстройки над каталогом.

Зачем это разделено? Штатный апдейтер работает с сервером обновлений «1С-Битрикс» и знает только про модули продукта. Партнёрские обновляются через свою систему — по коду партнёра и лицензионному ключу, которые вы указываете в карточке. Без этой связки модуль останется на версии, что была в момент покупки. Никакие фиксы от вендора до вас не доедут.

Страница Marketplace > Обновления решений показывает список дополнительных модулей, установленных на сайте, и их доступные версии. В контекстной панели есть кнопка «Проверить обновления» — она опрашивает сервер партнёра и подтягивает то, что вышло после вашей установки. Обновления модуля ставятся друг за другом строго по версиям: каждое содержит только дельту от предыдущего, поэтому перескочить через несколько релизов нельзя. Система проведёт их по цепочке.

Дальше всё как со штатным апдейтом: выбираете модуль, жмёте установку, ждёте завершения.

Что стоит держать в голове: перед обновлением партнёрского модуля мы всегда делаем бэкап и проверяем на тестовом стенде. Партнёрские релизы реже проходят такую же регрессию, как модули продукта, и конфликты с вашими кастомами возможны.

Отдельный момент — данные пользователей. Если модуль трогает профили, имеет смысл подстраховаться обработчиком на событии главного модуля и проверить поля до записи:

<?php
// /bitrix/php_interface/init.php
use Bitrix\Main\EventManager;

EventManager::getInstance()->addEventHandler(
    'main',
    'OnBeforeUserUpdate',
    'myOnBeforeUserUpdateHandler'
);

// Событие вызывается в методе CUser::Update до изменения параметров пользователя
// и может быть использовано для отмены изменения или переопределения некоторых полей
function myOnBeforeUserUpdateHandler(&$arFields)
{
    // пример: не даём затереть e-mail пустым значением
    if (array_key_exists('EMAIL', $arFields) && trim((string)$arFields['EMAIL']) === '') {
        unset($arFields['EMAIL']);
    }
}

Обработчик вешаем именно на OnBeforeUserUpdate — он стреляет до записи, поэтому откатить изменения или подменить поля можно без последствий. Логику внутри подгоняйте под свой модуль: у кого-то критичны телефоны, у кого-то — привязка к внешним ID.

Как указать код партнёра и лицензионный ключ для модуля

Распространённая ошибка: администратор обновил модуль, а в админке тот же модуль через день снова висит как «требует обновления». Или ещё хуже — обновление скачалось, но при установке вылетает «недостаточно прав» или «неверный ключ». Обычно причина одна: в карточке партнёра не заполнены Код партнёра и Лицензионный ключ. Эти два поля — пропуск в партнёрскую систему обновлений, через которую распространяются модули, купленные в Marketplace и у сторонних разработчиков.

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

Мы в студии заводим эти поля сразу после покупки модуля. Иначе через месяц кто-то из команды снова ловит ту же ошибку и тратит время на диагностику.

Разберёмся, что куда вводится. Код партнёра — это идентификатор, под которым вы публикуете собственные модули в Marketplace. Если вы разрабатываете свои решения и хотите получать по ним обновления через штатную систему, код нужен именно для этого. Лицензионный ключ — отдельная история: он даёт доступ к тестированию альфа-версий обновлений, которые автор модуля открывает только владельцам этого ключа. То есть код партнёра — про ваши модули как разработчика, лицензионный ключ — про ранний доступ к чужим обновлениям на этапе тестирования.

На практике это две независимые настройки в одной карточке. Заполнять их нужно там, где вы зарегистрированы как партнёр, — данные берутся из личного кабинета партнёра.

Порядок действий такой:

1. Открыть карточку партнёра в административном разделе системы обновлений.
2. Ввести Код партнёра — он используется как код для собственных модулей.
3. Ввести Лицензионный ключ — он открывает тестирование альфа-версий обновлений, доступных автору модуля.
4. Сохранить настройки и вернуться на закладку «Установка обновлений» — модуль появится в списке рекомендуемых.

Как собрать обновление для собственного модуля

Свой модуль — это не только код в /local/modules/, но и обязательство поддерживать его жизненный цикл. Если вы сами автор решения и планируете публиковать его через Marketplace, рано или поздно встаёт вопрос: как выпускать обновления так, чтобы у пользователей модуль подтягивал новые версии штатной кнопкой «Проверить обновления», а не переустанавливался вручную. У нас в практике это регулярно всплывает у студий, которые сделали внутренний модуль под клиента, а потом решили выложить его в Marketplace или отдавать по подписке другим проектам.

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

Дальше разберём, как это собирается штатным инструментом и что именно правится в файлах модуля.

Для сборки обновлений у «1С-Битрикс» есть отдельный инструмент — Конструктор модулей (bitrix.mpbuilder). Его ключевая особенность в том, что он собирает пакеты обновлений независимо от того, как модуль был создан — самим Конструктором или руками. То есть даже если вы писали модуль вручную, без мастера создания, вы всё равно можете подключить его к Конструктору и выпускать обновления через него.

Работает это так: Конструктор берёт содержимое модуля, сравнивает с предыдущей выпущенной версией и формирует пакет изменений. Обновления ставятся друг за другом в строгом соответствии с версией — каждое содержит лишь изменение по сравнению с предыдущим. Пропустить версию нельзя: пользователь со старой версией получит всю цепочку по порядку, и если в середине цепочки версия битая, дальше обновление не пойдёт.

Что стоит проверить перед сборкой в Конструкторе: корректный /install/version.php, актуальный /install/index.php с описанием модуля, отсутствие лишних файлов вроде локальных логов и бэкапов. Если модуль был создан вручную, Конструктор просто подхватит структуру — ничего пересобирать с нуля не потребуется.

<?php
// /install/version.php — минимальный обязательный файл модуля
$arModuleVersion = [
    'VERSION'      => '1.0.5',
    'VERSION_DATE' => '2025-02-14 12:00:00',
];

Что делать, если обновление модуля не устанавливается

Самая частая ситуация, с которой к нам приходят по этой теме: система обновлений показывает модуль как «требующий обновления», но при установке ничего не происходит — либо кнопка неактивна, либо процесс падает с ошибкой на середине. Причин обычно три: несовместимость версий модулей, отсутствие регистрации продукта или лицензионного ключа — без них система обновлений просто не отдаёт пакеты, и конфликт модулей, когда один требует версию другого, а она ещё не подтянулась. Обновления модуля ставятся друг за другом в строгом соответствии с версией; каждое обновление содержит лишь изменение по сравнению с предыдущим. Пропустили промежуточное звено — цепочка рвётся.

Разбираться с этим лучше по симптомам. Они довольно однозначно указывают на причину.

Действуем по шагам. Сначала проверяем регистрацию продукта: если она слетела или истёк лицензионный ключ, система обновлений не отдаст ни рекомендованные обновления модулей, ни опциональные (языковые файлы). Дальше обновляем саму систему обновлений. Как только для неё выходит новая версия, её нужно поставить первой, иначе она не сможет корректно обработать пакеты модулей. И только после этого смотрим логи: ошибки установки пишутся в журнал, и по тексту обычно сразу видно, какой модуль или какая версия стали камнем преткновения.

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

Обновление модуля вручную: когда штатный способ не работает

Ручное обновление — это не «альтернатива для продвинутых», а вынужденный обходной путь. К нему прибегают, когда штатный механизм физически не может достать до модуля. В нашей практике таких ситуаций три, и они довольно чётко очерчены.

Первая — нет доступа к админке или к системе обновлений. Продукт заблокирован за неуплату продления, лицензия истекла, сайт крутится на закрытом контуре без выхода в интернет. Вторая — кастомный модуль, который вы или сторонний подрядчик писали сами: в системе обновлений он не зарегистрирован, кода партнёра у него нет, и «Проверить обновления» его просто не увидит. Третья — старый продукт, который по тем или иным причинам больше не получает штатных обновлений, но модуль в нём обновить всё равно надо.

Что это даёт: закрыть дыру в конкретном модуле, не дожидаясь, пока вся система обновлений оживёт.

С чем комбинируется: с ручной сборкой обновления для собственного модуля — если вы автор, вы и архив готовите сами.

Общий порядок ручного обновления мы держим таким. Сначала скачиваем архив с новой версией модуля — у вендора, из репозитория или из собственной сборки. Затем распаковываем его в директорию модуля: для сторонних это /bitrix/modules/<код_модуля>/, для собственных — /local/modules/<код_модуля>/. Перед распаковкой обязательно делаем резервную копию текущей версии — откатиться иначе будет некуда.

Дальше проверяем файл /install/version.php внутри модуля: там лежат VERSION и VERSION_DATE. Именно эти значения система показывает в списке модулей, и если они не совпадут с реальным содержимым архива, вы получите модуль, который «числится» обновлённым, но фактически содержит старый код. Для собственных модулей эти поля можно обновлять автоматически при сборке — об этом мы говорили выше.

Какой вариант выбрать, зависит от того, кто автор. Если модуль ваш — правьте version.php руками или собирайте через Конструктор модулей. Если чужой — не трогайте метаданные, берите значения как есть из архива вендора.

Как проверить, что модуль обновился корректно

Процедура обновления завершилась без красных плашек — и это ещё не повод считать задачу закрытой. По нашему опыту, самые неприятные инциденты случаются не в момент установки, а через несколько часов или дней после: обновление формально встало, но часть изменений не применилась, обработчики событий остались от старой версии, а на боевом сайте уже работают пользователи. Поэтому проверку после обновления мы делаем отдельным шагом, а не «между делом».

Смотреть нужно на четыре вещи: фактическую версию модуля, содержимое /install/version.php, логи системы обновлений и поведение сайта в тестовом сценарии. Первые три дают формальное подтверждение. Четвёртая — реальное.

Если пропустить хотя бы одну, можно уйти в прод с обновлением, которое «как бы установилось».

• В админке: список модулей показывает установленную версию — сверьте её с той, что должна была прийти по цепочке обновлений.
• В файле /install/version.php модуля лежит дата и версия, которые используются при сборке обновлений — они должны совпадать с админкой.
• В логах системы обновлений (Update System) ищите сообщения о пропущенных или отложенных обновлениях, а не только об успешных.
• Тестовый сценарий: откройте публичную страницу, затронутую модулем, и проверьте, что ключевые функции работают как раньше.

Отдельная история — события, которые модуль регистрирует после обновления. Если модуль вешает обработчики через AddEventHandler (например, на OnBeforeUserUpdate или OnBeforeSocNetGroupUpdate), после обновления стоит убедиться, что они всё ещё подхватываются. Проверяется просто: открываем /bitrix/php_interface/init.php и модульные include.php, сверяем список зарегистрированных обработчиков с тем, что ожидаем увидеть. Затем прогоняем действие, которое этот обработчик должен ловить, и смотрим реакцию.

Если обработчик молчит — не спешите переписывать код. В большинстве случаев модуль просто не перерегистрировал события, и достаточно переустановить его через систему обновлений или сбросить кеш. Когда обработчик зарегистрирован через EventManager (D7-подход) — проверьте, что класс и метод существуют в новой версии: вендоры иногда переименовывают пространства имён.

И последнее: после обновления не лишним будет запустить проверку целостности через админку — она покажет, не осталось ли в модуле файлов от предыдущей версии, которые новая не перезаписала.

Подробнее об услуге: поддержка и сопровождение сайтов на Битрикс.