Прокси-сервер Vite не работает: причины и решения проблемы

Почему прокси-сервер Vite перестал работать и как это исправить

При разработке современных веб-приложений с помощью Vite прокси-сервер — незаменимый инструмент для обхода CORS-ошибок и интеграции с бэкендом. Но когда конфигурация прокси внезапно перестаёт функционировать, это парализует рабочий процесс. В этой статье мы разберём типичные причины сбоев проксирования в Vite и предоставим пошаговые инструкции по их устранению.

Основные причины сбоя прокси-сервера Vite

• Ошибки в конфигурационном файле vite.config.js — опечатки в пути, неправильный формат объекта proxy.
• Конфликт портов — когда бэкенд или другое приложение использует порт, назначенный для прокси.
• Проблемы с SSL-сертификатами — особенно при работе с HTTPS-бэкендами.
• Некорректные заголовки запросов — отсутствие CORS-заголовков или неверные настройки.
• Устаревшая версия Vite — баги в предыдущих релизах фреймворка.

Пошаговая настройка прокси в Vite

1. Создайте файл vite.config.js в корне проекта (если отсутствует).
2. Добавьте секцию proxy в раздел server:

   export default {
     server: {
       proxy: {
         '/api': {
           target: 'http://localhost:3000',
           changeOrigin: true,
           rewrite: (path) => path.replace(/^/api/, '')
         }
       }
     }
   }

3. Убедитесь, что порт target совпадает с портом вашего бэкенд-сервера.
4. Перезапустите сервер разработки командой npm run dev.

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

• Ошибка 404 при проксировании: Проверьте путь в rewrite-функции и убедитесь, что бэкенд-сервер запущен.
• CORS-ошибки сохраняются: Добавьте changeOrigin: true и настройте заголовки на бэкенде.
• Прокси игнорирует запросы: Убедитесь, что URL запроса начинается с указанного префикса (например, /api).
• HTTPS-соединение не работает: Для локального HTTPS используйте плагин @vitejs/plugin-basic-ssl.

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

• Q: Прокси работает в dev-режиме, но ломается после сборки?
  A: Прокси Vite предназначен только для разработки. Для продакшена настройте реверс-прокси через Nginx или Cloudflare.
• Q: Как проверить, что прокси активен?
  A: В консоли запуска Vite ищите строку Proxy created с указанием путей.
• Q: Можно ли проксировать несколько путей одновременно?
  A: Да, добавьте дополнительные ключи в объект proxy:

  proxy: {
    '/api': { ... },
    '/images': { ... }
  }

• Q: Почему прокси не перенаправляет cookie?
  A: Добавьте опцию cookieDomainRewrite: '' и проверьте настройки SameSite на бэкенде.

Профилактика и лучшие практики

Регулярно обновляйте Vite до актуальной версии, используйте .env-файлы для хранения URL бэкенда и проверяйте конфигурацию через console.log() при сложных сценариях. Для глубокой диагностики включите логгирование прокси добавлением опции configure: (proxy, options) => { proxy.on('error', console.error) }. Помните: 90% проблем решаются перезапуском сервера разработки после изменения конфига.