5 ошибок в кастомизации, из-за которых доработки ломаются
Кастомизация Битрикс24 — это не «добавить пару кнопок». Это изменение системы, которое влияет на работу людей и на совместимость с будущими обновлениями. Когда кастомизация сделана неправильно, она может годами работать, а потом сломаться при обновлении. Или конфликтовать с приложением из Маркетплейса. Или создавать технический долг, который невозможно поддерживать.
По опыту проектов, большинство проблем с кастомизацией возникает из-за нескольких повторяющихся ошибок: правки в системных файлах вместо папки /local/, отсутствие документации, несовместимость с обновлениями, конфликты с приложениями, отсутствие технического задания и тестирования. Эти ошибки не всегда очевидны: система работает, но через полгода выясняется, что обновление невозможно или новый разработчик не может разобраться в коде.
В этой статье — пять ошибок, которые чаще всего мешают кастомизации, и что делать вместо них. С примерами из практики, диагностикой и пошаговыми решениями. Если нужна кастомизация Битрикс24 под ваш процесс — поможем.
Ошибка 1: Правки в системных файлах
Симптом: После обновления Битрикс24 доработка пропала. Или система работает нестабильно. Или обновление не устанавливается.
Причина: Разработчик внёс изменения напрямую в файлы ядра или модулей (папки /bitrix/modules/, /bitrix/components/ и т.д.). При обновлении эти файлы перезаписываются, и доработка теряется.
Решение: Все изменения должны быть в папке /local/:
- Шаблоны. В
/local/templates/— копия шаблона с изменениями; - Компоненты. В
/local/components/— копия компонента с изменениями; - Модули. В
/local/modules/— свои модули или расширения; - Скрипты. В
/local/php_interface/— обработчики событий.
Папка /local/ не перезаписывается при обновлениях. Это значит, что ваши изменения сохранятся.
💡 Важно
Если разработчик говорит «я поправил в ядре, так быстрее», — это красный флаг. Быстрее сейчас, но при обновлении всё сломается.
Ошибка 2: Нет документации
Симптом: Через полгода никто не помнит, что делает доработка, зачем она нужна и как её поддерживать. Новый разработчик тратит недели на разбор кода.
Причина: Доработка сделана «на коленке», без описания. Нет схемы, нет комментариев, нет инструкции.
Решение: Документировать кастомизацию:
- Что сделано. Какие файлы изменены, какие модули добавлены;
- Зачем. Какую задачу решает доработка;
- Как работает. Схема, логика, зависимости;
- Как поддерживать. Что делать при обновлении, где искать ошибки.
Документация может быть в виде текстового файла, схемы или отдельного раздела в базе знаний. Главное — чтобы она была.
Ошибка 3: Несовместимость с обновлениями
Симптом: После обновления Битрикс24 доработка перестала работать. Или начала работать неправильно. Или появились ошибки в других частях системы.
Причина: Доработка использовала функции или методы, которые изменились в новой версии. Или была сделана без учёта будущих обновлений.
Решение:
- Использовать официальные API. Не лезть в «внутренности», которые могут измениться;
- Тестировать на тестовом стенде. Перед обновлением продакшена — обновить тестовую копию и проверить доработки;
- Следить за изменениями в API. Читать changelog, участвовать в бета-тестах;
- Разрабатывать с запасом. Не использовать функции, которые могут быть удалены.
Ошибка 4: Конфликты с приложениями из Маркетплейса
Симптом: После установки приложения из Маркетплейса доработка перестала работать. Или приложение не работает из-за доработки.
Причина: Доработка и приложение используют одни и те же хуки, события или поля. Или доработка изменяет поведение системы, которое ожидает приложение.
Решение:
- Проверять совместимость. Перед установкой приложения — проверить, не конфликтует ли оно с доработкой;
- Использовать уникальные префиксы. Для своих функций, событий, полей — использовать префикс, чтобы не пересекаться с другими;
- Тестировать на стенде. Установить приложение на тестовую копию и проверить;
- Документировать конфликты. Если конфликт неизбежен — описать его и найти решение.
Ошибка 5: Нет технического задания и тестирования
Симптом: Доработка сделана, но не решает задачу. Или решает, но не так, как ожидал заказчик. Или работает с ошибками.
Причина: Не было технического задания. Разработчик понял задачу по-своему, заказчик ожидал другого. Или не было тестирования — ошибки выявились в продакшене.
Решение:
- Составить ТЗ. Что должно быть сделано, как должно работать, какие сценарии;
- Согласовать ТЗ. Заказчик и разработчик должны понимать задачу одинаково;
- Тестировать. На тестовых данных, на разных сценариях, на разных устройствах;
- Принимать работу. Проверить, что всё работает так, как описано в ТЗ.
Без ТЗ и тестирования кастомизация превращается в лотерею: может сработать, а может — нет.
Чек-лист диагностики
Файлы
- Все изменения в
/local/ - Системные файлы не изменены
- Используются официальные API
Документация
- Описано, что сделано
- Описано, зачем
- Описано, как поддерживать
Обновления
- Есть тестовый стенд
- Доработки проверены на обновлении
- Нет конфликтов с Маркетплейсом
ТЗ и тесты
- Есть техническое задание
- Доработка протестирована
- Работа принята по ТЗ
Наши рекомендации
Что вы получаете, заказывая аудит у нас
- Проверку файлов — все ли изменения в
/local/; - Проверку документации — есть ли описание;
- Проверку совместимости — с обновлениями и Маркетплейсом;
- Проверку ТЗ — есть ли техническое задание;
- Тестирование — на тестовых данных;
- Исправление ошибок — с конкретными решениями;
- Обучение — как избегать ошибок в будущем.
📌 Итоговый вывод
Ошибки в кастомизации можно исправить, если знать, где искать.
Что нужно знать:
- Ошибка 1: правки в системных файлах — все изменения в
/local/; - Ошибка 2: нет документации — описывайте что, зачем, как;
- Ошибка 3: несовместимость с обновлениями — используйте официальные API, тестируйте;
- Ошибка 4: конфликты с Маркетплейсом — проверяйте совместимость, используйте префиксы;
- Ошибка 5: нет ТЗ и тестирования — составляйте ТЗ, тестируйте на стенде;
- Чек-лист: файлы, документация, обновления, ТЗ.
Также рекомендуем: Кастомизация, Кастомные роботы, Vibecode, все статьи.