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

Введение в Webpack Dev Server и проксирование запросов

Webpack Dev Server (WDS) — незаменимый инструмент для фронтенд-разработчиков, обеспечивающий горячую перезагрузку и удобную отладку. Однако при работе с API часто возникает проблема CORS (Cross-Origin Resource Sharing), когда фронтенд и бэкенд работают на разных доменах или портах. Здесь на помощь приходит проксирование — перенаправление запросов через WDS для обхода ограничений безопасности браузера. Ключевая настройка changeOrigin решает критически важную задачу корректной передачи заголовков.

Что такое опция changeOrigin и зачем она нужна?

Опция changeOrigin в конфигурации прокси Webpack Dev Server изменяет значение HTTP-заголовка Host в запросе. По умолчанию (changeOrigin: false) WDS отправляет исходный заголовок Host (например, localhost:3000). При активации (changeOrigin: true) заголовок заменяется на целевой домен бэкенд-сервера. Это необходимо, когда:

• Бэкенд проверяет заголовок Host для валидации запросов
• Сервер использует виртуальные хосты (например, в Nginx/Apache)
• Возникают ошибки 404 или 403 из-за несовпадения доменов

Настройка прокси с changeOrigin в Webpack

Добавьте раздел devServer.proxy в webpack.config.js:

module.exports = {
  devServer: {
    proxy: {
      '/api': {
        target: 'https://backend.example.com',
        changeOrigin: true, // Активируем изменение заголовка Host
        secure: false, // Для HTTPS с самоподписанными сертификатами
        pathRewrite: { '^/api': '' } // Опциональное удаление префикса
      }
    }
  }
};

Ключевые параметры:

• target: URL целевого сервера
• changeOrigin: true/false (влияет на заголовок Host)
• pathRewrite: перезапись пути запроса
• logLevel: ‘debug’ для детальных логов (рекомендуется при настройке)

Примеры конфигурации прокси

Базовый пример для REST API

proxy: {
  '/users': {
    target: 'http://api.myapp.com:8080',
    changeOrigin: true,
    headers: {
      Connection: 'keep-alive' // Дополнительные заголовки
    }
  }
}

Проксирование нескольких путей

proxy: [
  {
    context: ['/auth', '/profile'],
    target: 'https://auth-service.com',
    changeOrigin: true
  },
  {
    context: '/uploads',
    target: 'http://cdn.myapp.com',
    changeOrigin: false // Заголовок Host не изменяется
  }
]

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

• Ошибка 404 после настройки прокси
  • Проверьте pathRewrite и context
  • Убедитесь, что целевой URL доступен из сети
• CORS-ошибки сохраняются
  • Добавьте в бэкенд заголовок Access-Control-Allow-Origin: *
  • Проверьте changeOrigin: true и перезапустите WDS
• Не передаются куки
  • Установите cookieDomainRewrite: 'localhost'
  • Добавьте withCredentials: true в клиентские запросы

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

1. Что именно меняет changeOrigin?

При changeOrigin: true Webpack Dev Server заменяет заголовок Host в HTTP-запросе на домен из параметра target. Например, запрос с localhost:3000 к api.site.com будет отправлен с Host: api.site.com.

2. Когда обязательно использовать changeOrigin?

Когда бэкенд:

• Настроен на привязку к конкретному домену
• Использует SSL/TLS с проверкой домена
• Возвращает ошибки 403/404 из-за неверного Host

3. Как проверить работу прокси?

Используйте:

1. Инструменты разработчика браузера (вкладка Network)
2. Консоль Webpack Dev Server с logLevel: 'debug'
3. Утилиты типа curl: curl -x http://localhost:8080 http://yourdomain/api/test

4. Безопасно ли использовать changeOrigin в продакшене?

Нет! Webpack Dev Server предназначен ТОЛЬКО для разработки. В продакшене используйте Nginx, Apache или облачные прокси (Cloudflare, AWS ALB).

5. Как проксировать WebSockets?

Добавьте опцию ws: true в конфиг:

proxy: {
  '/socket': {
    target: 'ws://backend.com',
    changeOrigin: true,
    ws: true
  }
}