Отладка прокси в Webpack Dev Server: Полное руководство с примерами и FAQ

Что такое webpack-dev-server и зачем нужен прокси?

Webpack Dev Server (WDS) — инструмент для разработки, предоставляющий live reloading и hot module replacement. Проксирование критически важно для обхода CORS-ошибок при работе с API. Например, когда фронтенд на localhost:3000 обращается к бэкенду на api.example.com, браузер блокирует запросы из-за политики безопасности. Прокси WDS незаметно перенаправляет такие запросы, маскируя их под same-origin.

Настройка прокси в webpack-dev-server: шаг за шагом

Добавьте в webpack.config.js секцию devServer.proxy:

module.exports = {
  devServer: {
    proxy: {
      '/api': {
        target: 'https://api.example.com',
        changeOrigin: true,
        pathRewrite: { '^/api': '' },
        logLevel: 'debug' // Включаем логи для отладки
      }
    }
  }
};

• target: URL целевого сервера
• changeOrigin: подменяет заголовок Host (обязательно для внешних доменов)
• pathRewrite: удаляет префикс /api из пути
• logLevel: активирует детальные логи в консоли

Распространенные проблемы и отладка прокси (debug)

Типичные ошибки и методы диагностики:

1. 404 ошибки: Убедитесь, что pathRewrite корректно изменяет путь. Проверьте итоговый URL в логах WDS.
2. CORS сохраняется: Включите changeOrigin: true. Проверьте заголовки запроса через вкладку Network DevTools.
3. Прокси игнорирует запрос: Убедитесь, что путь в proxy-объекте (например, ‘/api’) совпадает с началом URL запроса.
4. SSL-ошибки: Для HTTPS-целей добавьте secure: false в конфигурацию (только для разработки!).

Инструменты отладки:

• Запустите WDS с флагом --inline --progress для детальных логов
• Используйте onProxyReq хуки для логирования сырых запросов
• Анализируйте ответы через curl или Postman, минуя прокси

Примеры конфигурации прокси для различных сценариев

Пример 1: Мульти-доменная маршрутизация

proxy: {
  '/users': { target: 'http://auth.service' },
  '/products': { target: 'http://catalog.service' }
}

Пример 2: Обработка WebSockets

proxy: {
  '/socket.io': {
    target: 'ws://chat.server',
    ws: true
  }
}

Пример 3: Контекст-зависимая конфигурация

proxy: [{
  context: ['/auth', '/api'],
  target: 'http://backend:8080',
  bypass: (req) => req.headers.accept.includes('html') ? '/index.html' : null
}]

Часто задаваемые вопросы (FAQ) по webpack-dev-server proxy

Q: Почему прокси не работает с HTTPS?
A: Добавьте secure: false в конфиг, но только для тестовых сертификатов. Для production используйте NGINX.

Q: Как логировать все прокси-запросы?
A: Установите logLevel: 'debug' или используйте хуки:

onProxyReq: (proxyReq, req) => {
  console.log(`[PROXY] ${req.method} → ${proxyReq.path}`)
}

Q: Можно ли проксировать только POST-запросы?
A: Да, через context с фильтрацией по методу:

context: (pathname, req) => req.method === 'POST' && pathname.startsWith('/api')

Q: Webpack Dev Server перезагружает страницу при проксировании. Как исправить?
A: Вероятно, сервер возвращает HTML при ошибках. Добавьте historyApiFallback: true и проверьте статусы ответов.

Q: Альтернативы встроенному прокси?
A: Для сложных сценариев используйте http-proxy-middleware напрямую или настройки внешнего прокси (Charles, Fiddler).