Webpack Dev Server Proxy Target: Полное Руководство по Настройке и Использованию

Что такое Webpack Dev Server Proxy Target?

Webpack Dev Server Proxy Target – ключевая настройка в экосистеме Webpack, позволяющая перенаправлять API-запросы во время разработки. Когда фронтенд-приложение работает на локальном сервере (обычно localhost:8080), а бэкенд API размещен на другом домене (например, api.example.com), возникают проблемы с CORS (Cross-Origin Resource Sharing). Прокси-таргет элегантно решает эту проблему, перенаправляя запросы через development-сервер, создавая иллюзию единого источника.

Как настроить Proxy Target в Webpack Dev Server

Базовая конфигурация добавляется в webpack.config.js в раздел devServer:

module.exports = {
  devServer: {
    proxy: {
      '/api': {
        target: 'https://api.example.com',
        changeOrigin: true,
        pathRewrite: {'^/api': ''}
      }
    }
  }
};

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

Практические сценарии использования

• Обход CORS ограничений: Все запросы идут через один домен, избегая блокировки браузером.
• Тестирование с разными средами: Легкое переключение между dev/staging/prod API заменой target.
• Мокинг API: Подмена ответов через прокси для тестирования edge-cases.
• Агрегация микросервисов: Перенаправление путей к разным бэкендам (/users → serviceA, /orders → serviceB).

Решения частых проблем

Проблема: Прокси игнорирует HTTPS-сертификаты.
Решение: Добавьте secure: false в конфигурацию.

Проблема: Не перезаписываются куки домена.
Решение: Используйте cookieDomainRewrite: 'localhost'.

Расширенные настройки прокси

proxy: {
  '/auth': {
    target: 'https://auth.service.com',
    ws: true, // поддержка WebSockets
    logLevel: 'debug' // детальные логи
  },
  '/uploads': {
    target: 'http://cdn.example.com',
    headers: {
      'X-Proxy': 'webpack-dev-server'
    }
  }
}

Часто задаваемые вопросы (FAQ)

Чем proxy отличается от CORS?

Прокси полностью избегает политики CORS, перенаправляя запросы через сервер разработки. CORS требует настройки заголовков на бэкенде.

Работает ли прокси с WebSockets?

Да! Добавьте опцию ws: true в конфигурацию прокси для поддержки WebSocket-соединений.

Как тестировать прокси без перезапуска dev server?

Используйте devServer: { hot: true } – большинство изменений в proxy применяются без перезагрузки.

Можно ли использовать несколько таргетов?

Да! Определите несколько ключей в объекте proxy для разных путей: '/api', '/images', '/graphql' с отдельными target.

Почему не работают POST-запросы через прокси?

Проверьте опцию changeOrigin: true и заголовки Content-Type. Добавьте onProxyReq для отладки тела запроса.

Заключение

Webpack Dev Server Proxy Target – незаменимый инструмент для современных фронтенд-разработчиков. Он не только решает проблемы CORS, но и предоставляет гибкий механизм интеграции с любыми бэкенд-сервисами. Правильная настройка прокси ускоряет разработку, позволяет тестировать сценарии с реальными API и упрощает работу в микросервисной архитектуре. Освоив продвинутые опции вроде pathRewrite и cookieDomainRewrite, вы сможете адаптировать прокси под самые сложные workflow.