Разработка uBlock Origin ведётся в открытом репозитории на GitHub под учётной записью gorhill, и любой желающий может склонировать исходный код, собрать расширение локально или предложить свои изменения через pull request. Проект написан преимущественно на JavaScript и не требует сложной инфраструктуры: для сборки достаточно установленного Python и инструментов командной строки, которые есть в большинстве систем.
В этой статье разберём, как устроен процесс разработки uBlock Origin: от клонирования репозитория и сборки до отладки собственных фильтров и отправки исправлений автору. Материал будет полезен как тем, кто хочет внести вклад в проект, так и пользователям, желающим собрать расширение из исходников самостоятельно.
Структура репозитория и технологический стек
Исходный код uBlock Origin расположен в репозитории uBlockOrigin/uBlock на GitHub. Основная логика расширения написана на чистом JavaScript без использования крупных фреймворков — автор проекта сознательно избегает тяжёлых зависимостей, чтобы сохранить контроль над производительностью и размером кода.
Ключевые директории репозитория включают src/ с основным кодом, platform/ с платформозависимыми частями для Chromium и Firefox, а также tools/ со скриптами сборки. Файлы локализации лежат в каталоге src/_locales/, и именно туда вносятся переводы интерфейса на разные языки.
- 📁
src/js/— ядро блокировщика, движок фильтрации и логика интерфейса - 📁
platform/— специфичный код для браузеров Chromium и Firefox - 📁
tools/— скрипты сборки и вспомогательные утилиты - 📁
assets/— встроенные списки фильтров и их метаданные
Сборка расширения из исходников
Для сборки uBlock Origin из исходного кода потребуется установленный Python 3 и утилита git. Сначала клонируйте репозиторий и перейдите в его директорию:
git clone https://github.com/gorhill/uBlock.git
cd uBlock
Сборка выполняется скриптом из каталога tools/. Для версии под Chromium используется команда:
tools/make-chromium.shГотовое расширение появится в директории dist/build/uBlock0.chromium/. Для Firefox есть отдельный скрипт tools/make-firefox.sh, который формирует пакет в формате XPI. Точные имена скриптов и их параметры могут меняться между версиями, поэтому перед сборкой стоит заглянуть в файл tools/README.md в актуальной версии репозитория.
⚠️ Внимание: расширение, собранное из исходников, не будет автоматически обновляться через магазин браузера. При выходе новой версии сборку придётся повторять вручную, иначе вы рискуете остаться на устаревшей версии с неактуальными исправлениями безопасности.
☑️ Проверка перед первой сборкой
Режим разработчика и отладка
В самом uBlock Origin есть встроенные инструменты, полезные при разработке и диагностике. На вкладке настроек расширения можно включить опцию «Я опытный пользователь», после чего становятся доступны динамические правила фильтрации и расширенная панель управления. Дополнительно в разделе скрытых настроек (advanced settings) доступны параметры, меняющие поведение движка.
Для отладки кода расширения используйте стандартные инструменты браузера. В Chromium откройте страницу chrome://extensions, включите режим разработчика и нажмите «Проверить представления» рядом с нужной страницей расширения. В Firefox аналогичная возможность доступна через about:debugging. Так вы получите доступ к консоли, точкам останова и инспектору фонового скрипта.
Разработка и тестирование собственных фильтров
Значительная часть «разработки» вокруг uBlock Origin — это создание и поддержка списков фильтров. Синтаксис фильтров uBlock Origin совместим с Adblock Plus, но расширен собственными возможностями: процедурными косметическими фильтрами, скриптлетами и расширенными сетевыми модификаторами.
Собственные правила добавляются на вкладке «Мои фильтры» в панели управления. Перед добавлением правила в публичный список его стоит проверить через логгер: убедиться, что оно блокирует целевой запрос и не ломает функциональность сайта. Для проверки косметических фильтров удобно использовать средство выбора элементов (element picker) — оно подсвечивает, какие узлы страницы попадут под правило.
| Тип правила | Назначение | Пример синтаксиса |
|---|---|---|
| Сетевой фильтр | Блокировка запроса к домену или URL | ||example.com/ads/ |
| Косметический фильтр | Скрытие элемента на странице | example.com##.banner |
| Скриптлет | Внедрение JS для нейтрализации антиблокировщиков | example.com##+js(nostif, ...) |
| Исключение | Отмена действия существующего фильтра | @@||example.com/needed.js |
⚠️ Внимание: при тестировании фильтров сначала отключайте сторонние списки и проверяйте правило в изоляции. Конфликт двух списков — частая причина ложных срабатываний, и без изоляции вы не поймёте, какой именно фильтр ломает страницу.
Участие в разработке проекта
Вклад в uBlock Origin возможен в нескольких форматах. Самый доступный — сообщения об ошибках через GitHub Issues, но здесь есть важный нюанс: прежде чем создавать issue, нужно воспроизвести проблему с настройками по умолчанию и без сторонних списков. Автор проекта строго следит за качеством репортов, и шаблон issue требует заполнения всех диагностических пунктов.
Исправления кода принимаются через pull request. Перед отправкой убедитесь, что изменение минимально, не ломает существующее поведение и сопровождается понятным описанием причины. Переводы интерфейса вносятся через платформу Crowdin, а не прямыми правками файлов локализации в репозитории.
- 🐛 Сообщения об ошибках — только с полной диагностикой по шаблону
- 🔧 Pull requests — минимальные, сфокусированные изменения
- 🌐 Переводы — через Crowdin, а не напрямую в git
- 📋 Фильтры — проблемы с ложными срабатываниями решаются в отдельном репозитории
uAssets
Почему автор отклоняет многие pull requests
Проект придерживается философии минимализма: каждое изменение увеличивает поверхность для ошибок и стоимость поддержки. Поэтому предложения новых функций часто отклоняются, даже если они технически грамотны. Перед серьёзной работой над фичей стоит обсудить идею в issue и получить обратную связь.
Manifest V3 и проект uBOL
Отдельное направление разработки связано с переходом Chrome на Manifest V3, который ограничивает возможности классических блокировщиков. В ответ на это автор создал отдельный проект — uBlock Origin Lite (uBOL), который работает в рамках нового API declarativeNetRequest. Его исходники также открыты и развиваются параллельно с основным проектом.
uBOL отличается архитектурно: фильтрация выполняется браузерным движком, а не кодом расширения, что снижает гибкость, но соответствует новым требованиям платформы. В Firefox оригинальный uBlock Origin продолжает работать на прежней модели, и разработка классической версии не прекращается.
Часто задаваемые вопросы
Нужно ли знать фреймворки для участия в разработке uBlock Origin?
Нет. Кодовая база написана на ванильном JavaScript без React, Vue и подобных инструментов. Достаточно уверенного владения JavaScript, понимания WebExtensions API и готовности читать существующий код проекта.
Можно ли установить собранную из исходников версию в Chrome?
Да, через страницу chrome://extensions с включённым режимом разработчика — кнопка «Загрузить распакованное расширение». Учтите, что браузер будет периодически напоминать о расширениях в режиме разработчика, а автообновления из магазина работать не будут.
Куда сообщать о ложной блокировке сайта?
Проблемы с фильтрами и ложными срабатываниями относятся к репозиторию uAssets, а не к основному коду расширения. Перед репортом воспроизведите проблему с настройками по умолчанию и приложите данные из логгера.
Как перевести интерфейс uBlock Origin на свой язык?
Переводы вносятся через платформу Crowdin, где у проекта есть официальная страница. Прямые правки файлов в src/_locales/ через pull request не принимаются, так как локализации синхронизируются автоматически.
Будет ли классический uBlock Origin работать в Chrome после перехода на Manifest V3?
Google поэтапно отключает поддержку Manifest V2 в Chrome, и точные сроки зависят от канала браузера и корпоративных политик. Для пользователей Chrome автор проекта развивает uBlock Origin Lite, а полная версия остаётся доступной в Firefox и браузерах, сохраняющих поддержку MV2.