Ошибка прокси запроса: причины и пошаговое исправление

Что означает ошибка ECONNREFUSED

Текст ошибки обычно выглядит так: [HPM] Error occurred while trying to proxy request: /api/data или Error occurred while trying to proxy request to http://localhost:3000. Она означает, что ваш прокси-сервер (часто это webpack-dev-server, Vite, Nginx или API-шлюз) попытался перенаправить запрос к целевому бэкенду, но операционная система отклонила попытку подключения. Прокси не получает HTTP-ответ, потому что на сетевом уровне соединение не было установлено. Это останавливает разработку, так как фронтенд не может получить данные от API, и требует немедленной настройки маршрутизации или проверки сетевых служб.

Причины возникновения

1. Не запущен или аварийно завершился целевой сервер (Node.js, Python, Go-микросервис).
2. Указан неверный порт, IP-адрес или опечатка в конфигурационном файле target.
3. Локальный брандмауэр или антивирус блокирует исходящие соединения на нестандартные порты.
4. Конфликт протоколов: прокси пытается подключиться по https, а целевой сервер слушает только http (или не настроен самоподписанный сертификат).
5. Ошибки маршрутизации в Docker-сетях: контейнеры находятся в разных виртуальных сетях и не видят друг друга по имени сервиса.

Способы решения

Способ 1: Проверка доступности целевого сервера

Первым делом убедитесь, что сервис, к которому вы проксируете запросы, действительно работает и доступен.

1. Откройте терминал и выполните команду:

curl -v http://localhost:<ВАШ_ПОРТ>/

2. Если в ответе вы видите Connection refused, значит процесс не запущен или слушает другой интерфейс (например, только IPv6).
3. Запустите бэкенд заново и проверьте логи на наличие ошибок при старте.

💡 Совет: Используйте netstat -tuln или lsof -i :<порт>, чтобы точно увидеть, на каком адресе и порту слушает ваш процесс.

Способ 2: Корректировка конфигурации прокси

Если сервер работает, но ошибка сохраняется, проверьте настройки маршрутизации в вашем инструменте разработки или веб-сервере.

Для Webpack Dev Server / Create React App:

// webpack.config.js или config файла devServer
module.exports = {
  devServer: {
    proxy: {
      '/api': {
        target: 'http://localhost:8080',
        changeOrigin: true,              // Подменяет Host в заголовке запроса
        secure: false,                   // Отключает проверку SSL для локальной разработки
        logLevel: 'debug'                // Включает детальный вывод в консоль
      }
    }
  }
};

⚠️ Важно: Параметр changeOrigin: true обязателен, если целевой сервер проверяет заголовок Host. Без него многие фреймворки сбрасывают соединение из соображений безопасности.

Способ 3: Настройка Docker-сетей и алиасов

Если вы разрабатываете в контейнерах, localhost внутри одного контейнера не указывает на хост-машину или другие контейнеры.

1. Убедитесь, что оба сервиса находятся в одной сети в docker-compose.yml:

services:
  frontend:
    environment:
      - PROXY_TARGET=http://backend:3000
    networks:
      - app_net
  backend:
    networks:
      - app_net
networks:
  app_net:
    driver: bridge

2. В конфигурации прокси замените localhost на имя сервиса (backend). Docker DNS автоматически резолвит его во внутренний IP.
3. Пересоберите и запустите стеки командой docker compose up -d --build.

Способ 4: Отключение файрвола или добавление правил

В некоторых ОС входящие/исходящие соединения на нестандартных портах блокируются по умолчанию политиками безопасности.

1. Откройте настройки брандмауэра вашей операционной системы.
2. Добавьте разрешающее правило для порта бэкенда (например, TCP 3000).
3. Если используете ufw на Linux, выполните:

sudo ufw allow 3000/tcp
sudo ufw reload

4. Перезапустите прокси-сервер и проверьте соединение. Для Windows Defender Firewall используйте PowerShell: New-NetFirewallRule -DisplayName "Allow Backend Proxy" -Direction Inbound -LocalPort 3000 -Protocol TCP -Action Allow.

Профилактика

Чтобы избежать повторения сбоя в будущем, внедрите несколько простых практик в рабочий процесс. Всегда используйте переменные окружения (.env) для хранения адресов прокси, а не хардкодьте URL в конфигурационных файлах. Это позволит быстро менять эндпоинты при развёртывании на разных серверах без риска опечаток. Настройте автоматический перезапуск прокси при изменении конфигов с помощью nodemon или встроенных watch режимов. Регулярно обновляйте пакеты http-proxy-middleware и аналоги, так как в новых версиях исправляются проблемы с обработкой Keep-Alive, WebSocket-соединений и таймаутов.