Webpack Dev Server Proxy Headers: Полное Руководство по Настройке и Решению Проблем

Что такое Webpack Dev Server Proxy и зачем нужны заголовки?

Webpack Dev Server (WDS) — инструмент для разработки, предоставляющий live reloading и горячую замену модулей. Прокси-функция WDS перенаправляет запросы с локального сервера на внешние API, решая проблемы CORS. Заголовки (headers) критически важны: они передают аутентификацию, cookies и метаданные, без которых бэкенд может отвергнуть запрос.

Как настроить прокси с кастомными заголовками в Webpack

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

module.exports = {
  devServer: {
    proxy: {
      '/api': {
        target: 'https://example.com',
        changeOrigin: true,
        headers: {
          'Authorization': 'Bearer YOUR_TOKEN',
          'X-Custom-Header': 'value'
        }
      }
    }
  }
};

• changeOrigin: Меняет заголовок Host на целевой домен (обязательно для избежания CORS).
• headers: Объект с кастомными заголовками для всех проксируемых запросов.

Типичные сценарии использования заголовков

• Аутентификация: Передача Authorization: Bearer ... к защищенным API.
• Куки и сессии: Включение withCredentials: true для кросс-доменных запросов.
• Кастомные метаданные: Отправка X-Request-Source: dev-server для аналитики.
• Обход CORS: Автоматическая установка Origin и Referer через changeOrigin.

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

• Заголовки не применяются: Убедитесь, что путь в /api совпадает с URL запроса. Используйте pathRewrite для сложных маршрутов.
• CORS-ошибки: Активируйте changeOrigin: true и проверьте настройки сервера (разрешите домен WDS).
• Потеря кук: Добавьте cookieDomainRewrite: 'localhost' и onProxyRes: (proxyRes) => { proxyRes.headers['set-cookie'] = proxyRes.headers['set-cookie']?.map(c => c.replace(/Secure/gi, '')); } для HTTPS.
• Уязвимости безопасности: Никогда не хардкодьте секретные ключи в конфиг! Используйте .env-файлы.

Динамические заголовки через onProxyReq

Для генерации заголовков в рантайме используйте хуки:

proxy: {
  '/api': {
    target: 'https://example.com',
    onProxyReq: (proxyReq, req) => {
      proxyReq.setHeader('X-User-ID', req.user.id); // Пример из Express-сессии
    }
  }
}

FAQ: Ответы на ключевые вопросы

Как передать куки через прокси?

Добавьте в конфиг: cookieDomainRewrite: { 'example.com': 'localhost' } и установите withCredentials: true в клиентских запросах (например, в Axios).

Почему заголовки Authorization не работают?

1. Проверьте опечатки в ключе headers.
2. Убедитесь, что changeOrigin: true активен.
3. Если используете динамический токен, внедрите его через onProxyReq.

Как отладить прокси-заголовки?

Включите логирование в WDS:

devServer: {
  proxy: {
    '/api': {
      target: 'https://example.com',
      logLevel: 'debug' // Выводит детали запросов в консоль
    }
  }
}

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

Да, через хук onProxyRes:

onProxyRes: (proxyRes) => {
  proxyRes.headers['cache-control'] = 'no-store';
}

Заключение

Настройка proxy headers в Webpack Dev Server упрощает разработку, эмулируя продакшен-окружение. Помните: корректные заголовки решают 90% проблем с CORS и аутентификацией. Тестируйте конфигурацию через logLevel: 'debug' и используйте хуки для сложных сценариев. Актуальные примеры ищите в официальной документации Webpack.