QR-код или ссылка не импортируются в sing-box: полная диагностика формата

Импорт профиля через QR-код или ссылку — один из самых удобных способов настроить sing-box. Однако часто при попытке добавить конфигурацию пользователь получает ошибку: «неверный формат», «не удалось импортировать» или просто ничего не происходит. В этой статье мы разберём по шагам, как диагностировать проблему и что проверять в зависимости от источника — клиент, core, сеть или сервер.

Основные причины ошибок импорта

Ошибки импорта можно разделить на четыре группы: неправильная URL-схема, повреждённый QR-код, невалидный JSON-профиль и несовместимость параметров. Частая ошибка — попытка импортировать ссылку от V2Ray или Clash в клиент sing-box, который ожидает определённый формат. Например, sing-box поддерживает схемы vless://, vmess://, trojan://, shadowsocks://, но не все подтипы. Необходимо также учитывать, что многие клиенты добавляют к ссылке дополнительные параметры, такие как #name для комментария, и если они закодированы неправильно, импорт не сработает.

Шаг 1. Проверяем ссылку и QR-код

Первым делом удостоверьтесь, что вы используете корректный формат ссылки. Возьмите исходную строку и раскодируйте её. Для этого можно воспользоваться онлайн-декодером Base64 или локальной командой echo '...' | base64 -d. Проверьте, нет ли лишних пробелов, символов перевода строки или невидимых символов. QR-код должен считываться полностью — иногда камера телефона обрезает часть кода. Убедитесь, что изображение чёткое и не повреждено. Если ссылка содержит символы, которые конфликтуют с URL-кодированием, замените их на %XX.

Шаг 2. Проверяем JSON-структуру профиля

Если импортируется файл конфигурации (например, через URL на GitHub), то это должен быть валидный JSON. Стандартный конфигурационный файл sing-box содержит секции log, inbounds, outbounds, route, dns, experimental. Проверьте структуру на соответствие официальной документации. Частые ошибки: пропущенная запятая между полями, лишняя запятая в конце массива, неверные кавычки (например, одинарные вместо двойных), или использование комментариев //, которые не поддерживаются. Для проверки используйте JSON-валидатор (например, jsonlint.com). Также обратите внимание на версию формата: некоторые поля устарели, и sing-box 1.11 может требовать новые имена.

Шаг 3. Диагностика route и DNS

Неправильная конфигурация маршрутизации или DNS может привести к тому, что импортированный профиль не будет работать, хотя формально импорт прошёл успешно. Проверьте, что в разделе route корректно заданы правила rules, типы action (например, route, hijack-dns, reject). Также убедитесь, что dns настроен верно: указаны серверы, fallback, strategy. Часто ошибки возникают из-за использования неподдерживаемых типов геоданных или отсутствия файлов geoip/geosite. В этом случае sing-box может выдать предупреждение при запуске, но импорт может завершиться ошибкой.

Шаг 4. Проверка TUN и transport

TUN-режим требует наличия прав администратора (или root на Android) и корректной настройки auto_route, strict_route, stack. Если импортируемая ссылка содержит параметры транспорта (например, network=ws для VLESS), убедитесь, что все поля заполнены: host, path, headers. Некорректно закодированные параметры в query-строке часто приводят к ошибке импорта. Например, ?type=ws&path=%2F&host=example.com должно быть правильно URL-закодировано. Некоторые клиенты автоматически добавляют эти параметры, но если ссылка содержит их уже, они должны быть корректными.

Шаг 5. Клиент, core, сеть и сервер

Если импорт прошёл, но соединение не устанавливается, проблема может быть на другом уровне. Проверьте логи клиента (GUI) — он может блокировать подозрительные ссылки или требовать подтверждения для каждого домена. Затем проверьте работу core (sing-box): запустите его вручную с флагом -D и смотрите вывод. Сетевая блокировка (например, через фаервол) также может помешать, особенно если сервер использует нестандартный порт. И наконец, убедитесь, что сам сервер работает и выгружает конфигурацию, соответствующую ссылке. Протестируйте сервер через другой клиент (например, официальный) или командой curl.

Частые сценарии и их решения

• Ошибка «Invalid URL» — проверьте схему ссылки; возможно, используется не поддерживаемый протокол.
• Ошибка «JSON parse error» — исправьте структуру конфигурационного файла.
• QR-код не считывается — очистите камеру, увеличьте контрастность, попробуйте другой сканер.
• После импорта профиль появляется, но не активен — проверьте настройки входа (inbounds), локальный порт.
• Импорт на iOS в приложении sing-box требует ручного добавления через URL-схему; убедитесь, что вы скопировали ссылку полностью.

Заключение

Диагностика импорта — это процесс исключения. Начните с формата ссылки, затем проверьте JSON, затем параметры маршрутизации и транспорта, и наконец окружение. Если проблема остаётся, обратитесь к актуальной официальной документации sing-box и проанализируйте логи. Помните: для каждого клиента могут быть свои особенности, но общая методология поиска причин одинакова.