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

Введение: Проблема кросс-доменных кук в разработке

При разработке фронтенд-приложений часто возникает проблема: фронтенд работает на localhost:3000, а бэкенд-API — на другом домене (например, api.example.com). Браузеры блокируют кросс-доменные запросы с куками из соображений безопасности. Это ломает аутентификацию и сессии. Решение? Прокси Webpack Dev Server! Этот инструмент перенаправляет запросы через development-сервер, создавая иллюзию одинакового домена.

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

Webpack Dev Server (WDS) — встроенный сервер для разработки с hot-reload. Его прокси-функция:

• Перехватывает запросы к определённым URL
• Перенаправляет их на целевой сервер (бэкенд)
• Модифицирует заголовки для обхода CORS
• Передаёт куки между доменами прозрачно для браузера

Без прокси куки теряются, вызывая ошибки 401/403. С ним браузер “видит” один домен, сохраняя сессии.

Настройка Proxy для работы с Cookies

Ключевые параметры в webpack.config.js для передачи кук:

1. target: URL бэкенд-сервера (https://api.example.com)
2. changeOrigin: true: Подменяет заголовок Host на целевой
3. secure: false: Разрешает HTTPS→HTTP (для dev-среды)
4. cookieDomainRewrite: Маппинг доменов кук
5. onProxyRes: Хук для модификации ответов

Без changeOrigin и cookieDomainRewrite куки могут игнорироваться!

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

// webpack.config.js
module.exports = {
  devServer: {
    proxy: {
      '/api': {
        target: 'https://backend.example.com',
        changeOrigin: true,
        secure: false,
        cookieDomainRewrite: {
          "backend.example.com": "localhost"
        },
        onProxyRes: (proxyRes) => {
          const cookies = proxyRes.headers['set-cookie'];
          if (cookies) {
            // Заменяем домен и Secure флаг
            const modifiedCookies = cookies.map(cookie => 
              cookie
                .replace(/Domain=backend.example.com/gi, 'Domain=localhost')
                .replace(/Secure;?/gi, '')
            );
            proxyRes.headers['set-cookie'] = modifiedCookies;
          }
        }
      }
    }
  }
};

Этот код:

• Перенаправляет /api → backend.example.com
• Перезаписывает Domain кук на localhost
• Удаляет флаг Secure (если бэкенд использует HTTPS)

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

• Куки не сохраняются: Проверьте cookieDomainRewrite и changeOrigin. Добавьте withCredentials: true в запросы фронтенда.
• CORS ошибки: Настройте заголовки на бэкенде: Access-Control-Allow-Origin: http://localhost:3000, Access-Control-Allow-Credentials: true.
• Сессия сбрасывается: Убедитесь, что SameSite атрибут кук не Lax/Strict. Для разработки используйте SameSite=None.
• HTTPS ошибки: При self-signed сертификатах добавьте secure: false и rejectUnauthorized: false в конфиг прокси.

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

Почему куки не отправляются через прокси?

Основные причины: не включен changeOrigin, отсутствует cookieDomainRewrite или фронтенд не использует withCredentials: true в запросах (axios/fetch).

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

1. Включите логирование в WDS: добавьте logLevel: 'debug' в devServer
2. Проверяйте Network в DevTools: смотрите заголовки Set-Cookie и Cookie
3. Используйте Postman для проверки бэкенда без CORS

Безопасно ли отключать Secure для кук?

Только в development! В production всегда используйте HTTPS и флаг Secure. Параметр secure: false в прокси — исключительно для локальной разработки.

Работает ли это с React/Vue?

Да! Прокси WDS не зависит от фреймворка. Конфигурация идентична для Create-React-App, Vue CLI и кастомного Webpack.

Альтернативы прокси Webpack?

• CORS-прокси (cors-anywhere)
• Настройка CORS на бэкенде
• Использование Chrome-флагов: --disable-web-security (небезопасно!)

Прокси WDS — наиболее правильное решение для разработки.

Итог: Настройка прокси Webpack Dev Server для кук решает проблемы аутентификации при разработке. Ключевые параметры: changeOrigin, cookieDomainRewrite и обработка заголовков. Тестируйте конфигурацию через DevTools и помните о безопасности в production!