Как настроить ngrok-туннелирование для локального проекта

Что такое ngrok?

ngrok — это инструмент, который создаёт безопасный туннель от публичного URL к вашему локальному серверу. Это позволяет показать ваш проект коллегам, протестировать вебхуки или проверить работу на мобильном устройстве — без деплоя.

Установка ngrok

macOS

Через Homebrew:

brew install ngrok

Windows

Через Chocolatey:

choco install ngrok

Или скачайте .zip архив с официального сайта, распакуйте и добавьте в PATH.

Linux

Через snap:

sudo snap install ngrok

Или через apt (Ubuntu/Debian):

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc   | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null   && echo "deb https://ngrok-agent.s3.amazonaws.com buster main"   | sudo tee /etc/apt/sources.list.d/ngrok.list   && sudo apt update   && sudo apt install ngrok

Регистрация и авторизация

1. Зарегистрируйтесь на dashboard.ngrok.com

2. Скопируйте ваш authtoken из дашборда

3. Добавьте токен:

ngrok config add-authtoken ВАШ_ТОКЕН

Эта команда одинакова для всех ОС.

Запуск туннеля

Убедитесь, что ваш локальный сервер запущен (например, на порту 3000), затем выполните:

Базовая команда (все ОС)

ngrok http 3000

После запуска вы увидите публичный URL вида:

Forwarding  https://xxxx-xxx-xx-xx-xxx.ngrok-free.app -> http://localhost:3000

С кастомным доменом (платный план)

ngrok http 3000 --domain=my-project.ngrok-free.app

Настройка Next.js для работы через ngrok

Если в проекте используется авторизация (например, NextAuth), необходимо обновить переменную окружения AUTH_URL:

# В файле .env.local
AUTH_URL=https://xxxx-xxx-xx-xx-xxx.ngrok-free.app

После изменения .env.local перезапустите dev-сервер:

npm run dev

Пошаговый пример

1. Запустите dev-сервер: npm run dev

2. В отдельном терминале запустите ngrok: ngrok http 3000

3. Скопируйте публичный URL из вывода ngrok

4. Обновите AUTH_URL в .env.local на этот URL

5. Перезапустите dev-сервер

Полезные флаги

Ограничения в России

ngrok периодически попадает в реестр блокировок Роскомнадзора. На практике ситуация неоднозначная:

• У некоторых провайдеров домены *.ngrok-free.app заблокированы, у других — работают без проблем

• Сам туннель (подключение к серверам ngrok) может работать даже при блокировке сайта

• Результат зависит от провайдера, региона и используемого DNS

Если ngrok не работает, попробуйте:

• Использовать VPN

• Сменить DNS на 1.1.1.1 (Cloudflare) или 8.8.8.8 (Google)

• Использовать альтернативы:

  • Cloudflare Tunnel: cloudflared tunnel --url http://localhost:3000

  • localhost.run: ssh -R 80:localhost:3000 nokey@localhost.run

  • Serveo: ssh -R 80:localhost:3000 serveo.net