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

В официальном примере Electron для Windows и Linux используются requestSingleInstanceLock и событие second-instance; на macOS получение URL показано через open-url. Документация проверена 22 октября 2026 года. Это разные пути доставки, поэтому обработчик одного события не покрывает все платформы. Проверяйте установленную сборку: запуск из среды разработки может иметь другую регистрацию протокола.

Матрица запуска быстро отделяет ошибку регистрации

СценарийЧто наблюдать
Программа закрытаНужная установленная сборка и один маршрут
Программа уже открытаСуществующий экземпляр принимает ссылку
Окно свёрнуто или скрытоНужное окно возвращается без дубля
UI ещё загружаетсяМаршрут ждёт готовности
Ссылка приходит повторноПереход не превращается в повтор опасного действия

Запишите платформу, версию сборки, момент запуска и обезличенное имя маршрута. Не пишите URL целиком, если в нём бывают секреты или коды входа. В журнале нужно различать «ОС вызвала обработчик», «экземпляр принял запрос» и «интерфейс открыл экран». Одно сообщение «deep link получен» скрывает потерю на следующей границе.

Окно может быть ещё не готово принять переход

Условная доставка:
системный обработчик -> разобрать разрешённый URL
действующий экземпляр -> очередь маршрутов
нужное окно готово -> передать конкретный маршрут
интерфейс подтвердил -> пометить доставку
окно скрыто -> показать по принятой UX-политике
действие с последствиями -> отдельная проверка и подтверждение

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

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

Тестируйте очередь ссылок, а не один удачный клик

  • Две разные ссылки приходят до готовности окна.
  • Одна ссылка повторяется после восстановления фокуса.
  • Ссылка указывает на недоступный текущему аккаунту объект.
  • Параметр отсутствует или содержит недопустимое значение.
  • Старая и новая установленные сборки не перехватывают схему случайно.

Определите политику нескольких переходов: выполнить по порядку, оставить последний или показать выбор. Она зависит от продукта и не должна возникать случайно из скорости загрузки renderer. Для операций с последствиями нужна самостоятельная защита от повтора на уровне операции; восстановление окна не должно повторно отправлять заказ или менять настройки.

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

Проверенные источники