Проверьте отдельно три вещи: кто зарегистрирован обработчиком протокола, сколько экземпляров приложения запустилось и какое окно получило маршрут. Регистрация схемы сама по себе не делает приложение одноэкземплярным. Начните с безопасной тестовой ссылки, которая только открывает экран, и сравните поведение закрытого и уже работающего приложения.
В официальном примере Electron для Windows и Linux используются requestSingleInstanceLock и событие second-instance; на macOS получение URL показано через open-url. Документация проверена 22 октября 2026 года. Это разные пути доставки, поэтому обработчик одного события не покрывает все платформы. Проверяйте установленную сборку: запуск из среды разработки может иметь другую регистрацию протокола.
Матрица запуска быстро отделяет ошибку регистрации
| Сценарий | Что наблюдать |
|---|---|
| Программа закрыта | Нужная установленная сборка и один маршрут |
| Программа уже открыта | Существующий экземпляр принимает ссылку |
| Окно свёрнуто или скрыто | Нужное окно возвращается без дубля |
| UI ещё загружается | Маршрут ждёт готовности |
| Ссылка приходит повторно | Переход не превращается в повтор опасного действия |
Запишите платформу, версию сборки, момент запуска и обезличенное имя маршрута. Не пишите URL целиком, если в нём бывают секреты или коды входа. В журнале нужно различать «ОС вызвала обработчик», «экземпляр принял запрос» и «интерфейс открыл экран». Одно сообщение «deep link получен» скрывает потерю на следующей границе.
Окно может быть ещё не готово принять переход
Условная доставка:
системный обработчик -> разобрать разрешённый URL
действующий экземпляр -> очередь маршрутов
нужное окно готово -> передать конкретный маршрут
интерфейс подтвердил -> пометить доставку
окно скрыто -> показать по принятой UX-политике
действие с последствиями -> отдельная проверка и подтверждениеНе отправляйте сообщение в первое найденное окно. У приложения могут быть настройки, экран входа и рабочий кабинет с разными аккаунтами. Маршрут должен попадать в подходящий контекст после проверки прав. Если пользователь не вошёл, сохраните только допустимое намерение открыть экран и продолжите после авторизации; ссылка не является разрешением на доступ к объекту.
Схему, путь и параметры разбирайте как недоверенный ввод. Разрешите ограниченный набор переходов, ограничьте размер данных и обработайте неизвестную команду понятным отказом. Не передавайте аргументы из URL в оболочку и не исполняйте произвольный код. Открытие карточки и выполнение операции должны оставаться разными действиями.
Тестируйте очередь ссылок, а не один удачный клик
- Две разные ссылки приходят до готовности окна.
- Одна ссылка повторяется после восстановления фокуса.
- Ссылка указывает на недоступный текущему аккаунту объект.
- Параметр отсутствует или содержит недопустимое значение.
- Старая и новая установленные сборки не перехватывают схему случайно.
Определите политику нескольких переходов: выполнить по порядку, оставить последний или показать выбор. Она зависит от продукта и не должна возникать случайно из скорости загрузки renderer. Для операций с последствиями нужна самостоятельная защита от повтора на уровне операции; восстановление окна не должно повторно отправлять заказ или менять настройки.
После исправления проверьте холодный запуск, повторный запуск и установленный пакет на каждой поддерживаемой ОС. Для разбора подготовьте обезличенную последовательность событий и правила маршрутов. Если регистрация указывает на старую сборку, чините установочный процесс, а не добавляйте ещё одно окно в обработчик приложения.