Решение проблем

Всегда начинайте со строки состояния внизу окна (или joppa status): она показывает, работает ли прокси, одобрен ли CA и сколько доменов отвечает.

Домен не отвечает

joppa diagnose <домен> (или инструмент MCP diagnose) сразу проверяет всё перечисленное ниже и говорит, что исправить: прокси, разрешение имени, сертификат, порт сервера разработки и состояние процесса, который должен его занимать.

Браузер не находит сайт (DNS_PROBE_FINISHED_NXDOMAIN). Имя .test не разрешается в ваш компьютер: строка состояния показывает .test не разрешается. Нажмите на неё или на Настроить / Исправить в баннере: Joppa запишет свой файл резолвера (с вашим паролем) и сбросит кеш DNS. Настройки › Разрешение .test › Проверить домен точно скажет, в чём проблема:

Сообщение	Что делать
«Пока ни один системный файл не направляет .test к Joppa»	Настроить
«Система пока не разрешает …»	Исправить: перезаписывает файл и сбрасывает кеш
«… разрешается в 10.…, а не в этот компьютер»	За `.test` отвечает VPN или DNS сети: Исправить перезаписывает файл Joppa и сбрасывает кеш; если VPN навязывает свой DNS, добавьте домен в `/etc/hosts`
«DNS-сервер Joppa не работает»	Порт 15353 занят другой программой: освободите его, затем перезапустите Joppa
«… доходит до Joppa, но ни один проект его не маршрутизирует»	Добавьте домен в проект

См. Установка › Разрешение доменов .test.

«Сервер разработки не отвечает» (502). Прокси работает, но на целевом порту никто не слушает. Запустите сервер разработки, проверьте его порт на вкладке «Домены» или позвольте Joppa запустить его из Процессов.

«Домен не настроен». Это имя не привязано ни к одному проекту, или домен выключен. Добавьте его на вкладке «Домены».

Вообще ничего не отвечает. Прокси остановлен (баннер вверху окна): Запустить прокси.

«Blocked request. This host is not allowed.»

Vite или Astro отклоняют домен. Вкладка Домены предлагает Исправить файл. См. Настройки фреймворка.

Браузер показывает «Не защищено»

Система не доверяет CA: строка состояния показывает CA … не доверенный. Нажмите Одобрить в баннере вверху окна (или Одобрить центр сертификации в Настройки › Центр сертификации), затем перезапустите браузер. В Linux также импортируйте CA в Firefox. См. Сертификаты.

Сгенерированные URL начинаются с http://

Ваш фреймворк не знает, что работает за HTTPS-прокси. Laravel: см. Laravel за прокси. Остальные фреймворки читают X-Forwarded-Proto.

Прокси не запускается

Порт 443 занят другим сервером (Lerd, Laravel Herd, Valet, Apache, Caddy, MAMP, DDEV, контейнер…): баннер называет его («Порт 443 занят: …») и предлагает его остановить, а затем запускает прокси. См. Порты 80 и 443 заняты.
Баннер не знает, кто это («процесс другого пользователя»): выполните показанную команду (sudo lsof -nP -iTCP:443 -sTCP:LISTEN), остановите эту программу, затем Запустить прокси.
Linux, отказано в доступе: sudo setcap cap_net_bind_service=+ep <путь к joppa>.
«Перенаправление HTTP → HTTPS выключено»: занят только порт 80; HTTPS работает.

Сервис не запускается

«Нет среды контейнеров»: установите или запустите OrbStack, Docker Desktop, Colima или Podman. См. Среды выполнения контейнеров.
«Порт 5432 занят: …»: работает другой PostgreSQL (Homebrew, Postgres.app, Docker). Освободить порт или Сменить порт. См. Порт занят.
Первый запуск с расширениями: сборка образа PostgreSQL занимает несколько минут.

Процесс постоянно падает

Откройте терминал (⌘ J) и вкладку процесса: там последняя ошибка. После выбранного числа перезапусков Joppa сдаётся и сообщает об этом. См. Перезапуск после сбоя.

Проект не видит новые переменные

Серверы разработки перечитывают .env только при запуске: перезапустите их (на вкладке «Процессы», если их запускает Joppa).

Vite+ не устанавливается

Joppa устанавливает Vite+ при первом запуске; без подключения к сети установка не удаётся, и шаблоны JavaScript остаются неактивными. Когда сеть появится, нажмите Повторить в окне Новый проект или в Настройки › Node. Установка скачивает официальный скрипт с https://vite.plus, затем Node LTS и bun с их сайтов. См. Версии Node, bun и PHP.

Телефон не открывает общий сайт

Для общего доступа в локальной сети:

Одна сеть. Телефон должен быть в той же сети Wi-Fi, что и Mac, а не в 4G/5G. Гостевой или публичный Wi-Fi часто изолирует устройства друг от друга: попробуйте другую сеть или публичную ссылку.
Брандмауэр macOS. Если вы отклонили запрос на входящие подключения: Системные настройки › Сеть › Брандмауэр › Параметры, и разрешите Joppa. Если отмечено «Блокировать все входящие подключения», ничего не пройдёт.
VPN. Включённый на Mac VPN может подменить адрес Wi-Fi своим. Выключите его, затем выключите и снова включите общий доступ.
Страница открывается, но без скриптов или API: они приходят с другого домена .test, которого телефон не знает. Откройте доступ и к этому домену или см. Что видит приложение.
Вход не сохраняется (вас возвращает на страницу входа): cookie __Secure- или __Host- требует HTTPS; используйте публичную ссылку.

Публичная ссылка не открывается

«Туннель закрылся»: окно показывает последние сообщения клиента. Чаще всего сеть блокирует исходящие соединения (корпоративный прокси, брандмауэр) или сервис временно недоступен; Повторить или выберите другой туннель.
cloudflared отказывается создавать быстрый туннель, если существует файл ~/.cloudflared/config.yml (или config.yaml) — файл именованного туннеля: переименуйте его на время общего доступа.
ngrok: без токена (в Joppa или в ngrok config add-authtoken) ngrok не запускается.
Pinggy закрывает бесплатный туннель через 60 минут: откройте его снова (адрес изменится).
Скачивание cloudflared завершается ошибкой «неверная контрольная сумма»: полученный архив не совпадает с опубликованным Cloudflare (прокси, изменяющий загрузки, повреждённый файл). Joppa удалил его; попробуйте снова в другой сети или установите cloudflared сами (brew install cloudflared).

Команда joppa говорит, что Joppa не запущен

Код выхода 3. Запустите приложение или добавьте --launch. Если приложение работает, переустановите команду в Настройки › Командная строка.

Сообщить об ошибке

Сообщить об ошибке внизу боковой панели (или в палитре ⌘ K) отправляет отчёт команде, без аккаунта:

Если на этом Mac активирована лицензия, форма открывается сразу: мы ответим на адрес лицензии.
Иначе введите свой адрес эл. почты и нажмите Получить код: на почту придёт 6-значный код. Введите его, затем Подтвердить. Адрес запоминается на этом Mac на 30 дней; Изменить адрес забывает его.
Опишите, Что не так, затем Подробности (что вы делали, что произошло, чего вы ожидали) и нажмите Отправить отчёт (⌘ ↵).

Версия Joppa и сведения о системе прикладываются. Вы получите копию с номером (JP-…); мы ответим на ваш адрес.

Приложить недавние логи, включено по умолчанию, добавляет последние строки журнала Joppa (не более 150 КБ), ваша домашняя папка записывается как ~. Посмотреть, что отправляется показывает их до отправки. Они приходят команде как вложение к отчёту и не хранятся на сайте.

Документация, чуть выше, открывает эту документацию на языке приложения.

Всё ещё не получается?

Напишите нам из приложения: Поддержка внизу боковой панели (или «Написать в поддержку» в палитре ⌘ K). Версия Joppa и сведения о системе прикладываются к сообщению. Если лицензия не активирована, приложение отправит вас на getjoppa.com: вы получите ссылку для входа по эл. почте, с лицензией или без, затем откроется форма. Та же форма доступна из подвала сайта.

Можно также написать на [email protected], приложив вывод joppa status. Для простого вопроса: [email protected].