Настройка proxy в Nuxt

Введение

Когда вы создаёте современное приложение на Nuxt, нередко возникает задача взаимодействия с внешними API или серверными ресурсами. Однако, если обращаться к сторонним сервисам напрямую из браузера, часто возникает проблема с политикой безопасности браузера (CORS). Здесь на помощь приходит настройка proxy – промежуточного слоя, который принимает ваши запросы и перенаправляет их к нужному серверу, скрывая детали реализации и повышая безопасность. Proxy также используется для маскировки запросов, балансировки нагрузки и даже для подмены заголовков.

В рамках этой статьи вы узнаете, как правильно настроить proxy в Nuxt, какие существуют способы для разных версий Nuxt, с какими подводными камнями можно столкнуться и как их обойти. Мы подробно рассмотрим настройку Nuxt 2 (наиболее часто используемый вариант) и коснёмся особенностей Nuxt 3.

Что такое proxy и зачем он нужен в Nuxt

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

• Решать проблему CORS (междоменных ограничений браузера)
• Скрывать реальные адреса API или сокращать длинные урлы
• Балансировать или фильтровать трафик
• Ограничивать доступность API только с вашего сервера
• Упрощать работу с переменными среды (различные адреса для dev, staging, prod)

В Nuxt proxy проще всего интегрируется через модуль @nuxtjs/proxy (Nuxt 2) и с помощью встроенного middleware или кастомных серверных хендлеров (Nuxt 3).

Настройка прокси необходима для обхода CORS-ограничений и организации безопасного доступа к API в Nuxt-приложениях. Но для правильной настройки прокси нужно понимать, как работает HTTP-протокол, как настроить заголовки запросов и как обеспечить безопасность передаваемых данных. Если вы хотите углубить свои знания о настройке прокси в Nuxt, приходите на наш большой курс Nuxt - fullstack Vue фреймворк. На курсе 129 уроков и 13 упражнений, AI-тренажеры для безлимитной практики с кодом и задачами 24/7, решение задач с живым ревью наставника, еженедельные встречи с менторами.

Настройка proxy в Nuxt 2

Установка необходимых модулей

В Nuxt 2 самым простым вариантом является использование пакета @nuxtjs/proxy вместе с @nuxtjs/axios (или другим http клиентом). Давайте начнём с установки этих пакетов:

npm install @nuxtjs/axios @nuxtjs/proxy
# или
yarn add @nuxtjs/axios @nuxtjs/proxy

@nuxtjs/proxy работает в связке с axios: все запросы автоматически перенаправляются через прокси, если заданы соответствующие правила.

Подключение модулей в nuxt.config.js

Добавьте модули в секцию modules вашего nuxt.config.js:

export default {
  modules: [
    '@nuxtjs/axios', // модуль axios
    '@nuxtjs/proxy', // модуль proxy
  ],

  axios: {
    proxy: true, // включаем proxy для axios
  },

  proxy: {
    // сюда будем добавлять правила проксирования
  }
}

В данном случае опция proxy: true в axios включает работу через прокси.

Базовое правило для proxy

Давайте рассмотрим простейший вариант: вы хотите все запросы к /api перенаправлять на https://jsonplaceholder.typicode.com.

proxy: {
  '/api/': {
    target: 'https://jsonplaceholder.typicode.com',
    pathRewrite: {'^/api/': ''},
    changeOrigin: true,
    secure: false // если обращаетесь к серверу с самоподписанным сертификатом
  }
}

Смотрите, что здесь происходит:

• Все запросы, начинающиеся с /api/, перенаправляются на указанный сервер
• pathRewrite убирает из запроса /api/ (например, запрос к /api/posts будет отправлен как /posts)
• changeOrigin — подменяет Origin хедера на новый target, что помогает обойти CORS
• secure ставьте false только для тестовых целей (например, если у target стоит самоподписанный SSL)

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

// Вы можете вызывать в своей логике:
this.$axios.get('/api/posts')
// На сервер уйдёт запрос на https://jsonplaceholder.typicode.com/posts

Таким образом все внутренние обращения через /api будут “маскированы” локально, а proxy сам отправит их дальше.

Дополнительные опции для proxy

Proxy можно настраивать довольно гибко:

proxy: {
  '/api/': {
    target: 'https://external.api.example',
    pathRewrite: {'^/api/': ''},
    ws: true, // если нужно проксировать websocket
    changeOrigin: true,
    onProxyReq(proxyReq, req, res) {
      // Здесь можно модифицировать запрос
      proxyReq.setHeader('x-added', 'foobar');
    }
  }
}

• ws: true — включает поддержку WebSocket
• onProxyReq — позволяет динамически менять хедеры и так далее

Обратите внимание, что каждое правило прокси можно делать максимально кастомным.

Прокси для разных путей и серверов

Модель proxy поддерживает несколько путей одновременно:

proxy: {
  '/api/': {
    target: 'https://api1.example',
    pathRewrite: {'^/api/': ''},
    changeOrigin: true,
  },
  '/auth/': {
    target: 'https://auth.example',
    pathRewrite: {'^/auth/': ''},
    changeOrigin: true,
  }
}

Теперь /api/users попадёт в один сервер, а /auth/login — в другой.

Прокси и переменные среды

Часто в зависимости от окружения (разработка, prod) вам требуется направлять запросы на разные адреса. Обычно используют переменные среды:

const API_URL = process.env.API_URL || 'https://default.api.server';

export default {
  proxy: {
    '/api/': {
      target: API_URL,
      pathRewrite: {'^/api/': ''},
      changeOrigin: true,
    }
  }
}

В .env:

API_URL=https://dev.api.server

Теперь меняя .env для разных окружений, вы контролируете target.

Настройка proxy в Nuxt 3

Nuxt 3 упростил и основательно пересмотрел архитектуру серверной части. Здесь уже нет стандартного модуля proxy, но вам доступны более гибкие инструменты на уровне серверных middleware и composable функций.

Прокси с помощью серверных middleware

Основной подход — создание собственного серверного middleware. Пример ниже показывает, как проксировать любые запросы к /api на внешний сервер:

Создание middleware

Создайте файл server/middleware/proxy.ts (или .js):

import { createProxyMiddleware } from 'http-proxy-middleware';

// Настройка мидлвара через http-proxy-middleware
export default createProxyMiddleware('/api', {
  target: 'https://jsonplaceholder.typicode.com',
  pathRewrite: { '^/api': '' },
  changeOrigin: true,
  secure: false
});

Здесь используется внешний пакет http-proxy-middleware. Не забудьте установить его заранее:

npm install http-proxy-middleware

Регистрируем middleware

Nuxt 3 обнаруживает все файлы в папке server/middleware/ автоматически; ваше “прокси” начинает работать сразу после рестарта сервера.

Слои & прокси через composable

Для более сложных сценариев прокси можно создать специальную функцию в /server/routes, где вы программно делаете fetch или axios:

export default defineEventHandler(async (event) => {
  // Извлекаем, куда ушёл запрос, динамически
  const path = event.req.url?.replace('/api/', '') || '';

  // Проксируем запрос на целевой сервер
  const response = await $fetch(`https://jsonplaceholder.typicode.com/${path}`, {
    method: event.req.method,
    headers: event.req.headers, // проксировать хедеры при необходимости
    body: event.req.method !== 'GET' && event.req.method !== 'HEAD'
      ? await readBody(event)
      : undefined
  });

  return response;
});

Этот способ сложнее, но даёт полный контроль: вы можете фильтровать/подменять запросы, работать с хедерами и кэшировать ответы.

Использование переменных среды

В Nuxt 3 рекомендуется также выносить адрес сервера в переменные окружения и получать их через useRuntimeConfig:

const config = useRuntimeConfig();

export default defineEventHandler(async (event) => {
  const path = event.req.url?.replace('/api/', '') || '';
  const url = `${config.public.apiUrl}/${path}`;

  // Прокси запрос на указанный сервер
  const response = await $fetch(url, {
    method: event.req.method,
    headers: event.req.headers
  });

  return response;
});

В nuxt.config.ts:

export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      apiUrl: process.env.API_URL || 'https://jsonplaceholder.typicode.com'
    }
  }
});

И в .env:

API_URL=https://production.api

Практические рекомендации и особенности

Когда использовать proxy, а когда нет

Proxy требуется только для внешних API, к которым нельзя или не стоит обращаться напрямую из браузера. Если ваше API принадлежит вашему домену и CORS не мешает, прокси можно не использовать. Однако наличие proxy даёт единый стандарт обращений к API на фронте, повышает переносимость кода и часто облегчает отладку.

Безопасность

Используйте proxy только для передачи запросов, которые действительно должны проксироваться. Не делайте универсальное “/” — открытый прокси — это опасно!

Не забывайте о rate limiting и логировании, чтобы через ваш proxy не шёл вредоносный трафик или “накачка” ваших ресурсов.

Debug и отладка proxy

Часто проблемы возникают из-за неправильной pathRewrite или недоступности target. Попробуйте локально проверить target через curl или Postman, убедитесь в корректности заголовков и правильно обрабатывайте ошибки, поднимаемые proxy.

Proxy и SSR

В режиме SSR (server-side rendering) ваши запросы идут с Node.js сервера, что позволяет обращаться к внешним API, минуя ограничения браузера. Но если вы делаете universal-приложение, где часть запросов уходит с клиента, а часть — с сервера, proxy всё равно понадобиться для унификации логики.

Заключение

Настройка proxy в Nuxt — необходимый навык для любого разработчика, работающего с внешними API. Через proxy можно решить основные проблемы безопасности и CORS, удобно управлять адресами серверов для разных окружений и стандартизировать логику обращения к API.

В Nuxt 2 для этого удобно использовать модуль @nuxtjs/proxy, который легко интегрируется и даёт гибкие возможности настройки прямо через nuxt.config.js. В Nuxt 3 проксирование реализуется через серверные middleware или кастомные обработчики, что позволяет строить более гибкие и мощные архитектуры.

Используйте proxy там, где это нужно, следите за безопасностью и грамотно разграничивайте доступ для разных маршрутов.

Настройка прокси — это важный аспект веб-разработки. Чтобы создавать гибкие и масштабируемые приложения, необходимо освоить все возможности фреймворка, включая работу с сервером, базами данных и API. На нашем курсе Nuxt - fullstack Vue фреймворк вы найдете все необходимые знания и навыки для достижения успеха. В первых 3 модулях уже доступно бесплатное содержание — начните погружаться в Nuxt прямо сегодня.

Частозадаваемые технические вопросы по теме

Как проксировать WebSocket соединения через Nuxt proxy?

В Nuxt 2 в конфиге proxy добавьте опцию ws: true:

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

В Nuxt 3 проксируйте через http-proxy-middleware с той же опцией ws: true.

Как исключить определённые пути из прокси?

Используйте функцию filter или custom onProxyReq/onProxyRes, чтобы обрабатывать только нужные маршруты, а остальные прокидывать дальше.

Почему proxy не работает в режиме generate/static?

Proxy действует только на сервере разработки (dev) или production сервере с SSR. В статически сгенерированном режиме сервер Nuxt отсутствует — используйте внешний nginx или другой прокси, либо делайте запросы из клиента напрямую к API.

Как проксировать несколько разных доменов одновременно?

Добавьте несколько правил в секцию proxy — каждое должно соответствовать своему префиксу и target.

Как передавать cookie и заголовки через proxy?

В proxy автоматически передаются большинство хедеров, но некоторые (например, cookie, authorization) могут быть отброшены целевым сервером. Убедитесь, что выставили changeOrigin: true и явно передаете нужные заголовки в onProxyReq, если требуется.