Параметры сервера

Если не указано иное, параметры в этом разделе применяются только в режиме разработки.

server.host

Тип: string | boolean
По умолчанию: 'localhost'

Укажите, на каких IP-адресах сервер должен прослушивать запросы. Установите это значение на 0.0.0.0 или true, чтобы прослушивать все адреса, включая локальные и публичные.

Это можно установить через CLI, используя --host 0.0.0.0 или --host.

ПРИМЕЧАНИЕ

Существуют случаи, когда другие серверы могут отвечать вместо Vite.

Первый случай — когда используется localhost. Функция Node.js dns.setDefaultResultOrder меняет порядок адресов, полученных через DNS, и браузеры могут использовать другой разрешённый адрес, отличный от того, на котором слушает Vite. Vite выводит разрешённый адрес, если он отличается.

Второй случай — это когда используются wildcard-хосты (например, 0.0.0.0). Это связано с тем, что серверы, слушающие на не-wildcard-хостах, имеют приоритет над теми, которые слушают на wildcard-хостах.

Доступ к серверу на WSL2 из вашей локальной сети

При запуске Vite на WSL2 недостаточно установить host: true, чтобы получить доступ к серверу из вашей локальной сети. Смотрите документацию по WSL для получения дополнительных сведений.

server.allowedHosts

Тип: string[] | true
По умолчанию: []

Имена хостов, на которые Vite разрешено отвечать. localhost и домены под .localhost, а также все IP-адреса разрешены по умолчанию. При использовании HTTPS эта проверка пропускается.

Если строка начинается с ., это позволит использовать это имя хоста без ., а также все его поддомены. Например, .example.com разрешит доступ к example.com, foo.example.com и foo.bar.example.com. Если установлено значение true, серверу разрешено отвечать на запросы для любых хостов.

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

Хосты, над которыми у вас есть контроль и которые вы можете разрешить по IP-адресам, безопасно добавлять в список разрешённых хостов.

Например, если вы владеете доменом vite.dev, вы можете добавить vite.dev и .vite.dev в список. Если вы не владеете этим доменом и не можете доверять его владельцу, вы не должны его добавлять.

В частности, вы никогда не должны добавлять в этот список домены верхнего уровня, такие как .com. Это объясняется тем, что любой желающий может зарегистрировать домен, такой как example.com, и управлять IP-адресом, на который он указывает.

ОПАСНОСТЬ

Установка server.allowedHosts в значение true позволяет любому веб-сайту отправлять запросы на ваш сервер разработки через атаки с подменой DNS, что дает возможность загружать ваш исходный код и контент. Мы рекомендуем всегда использовать явный список разрешённых хостов. См. GHSA-vg6x-rcgg-rjx6 для получения дополнительной информации.

Настройка через переменную окружения

Вы можете установить переменную окружения __VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS, чтобы добавить дополнительные разрешённые хосты. Используйте запятые для разделения нескольких хостов (например, host1.example.com,host2.example.com).

server.port

Тип: number
По умолчанию: 5173

Укажите порт сервера. Обратите внимание, что если порт уже используется, Vite автоматически попытается использовать следующий доступный порт, поэтому это может быть не тот порт, на котором в конечном итоге будет слушать сервер.

server.strictPort

Тип: boolean

Установите значение true, чтобы выйти, если порт уже используется, вместо того чтобы автоматически пытаться использовать следующий доступный порт.

server.https

Тип: https.ServerOptions

Включите TLS + HTTP/2. Значение является объектом options, переданным в https.createServer().

Необходим действительный сертификат. Для базовой настройки вы можете добавить @vitejs/plugin-basic-ssl в плагины проекта, который автоматически создаст и кэширует самоподписанный сертификат. Однако мы рекомендуем создавать свои собственные сертификаты.

server.open

Тип: boolean | string

Автоматически открывать приложение в браузере при запуске сервера. Когда значение является строкой, оно будет использоваться как путь URL. Если вы хотите открыть сервер в конкретном браузере, который вам нравится, вы можете установить переменную окружения process.env.BROWSER (например, firefox). Вы также можете установить process.env.BROWSER_ARGS, чтобы передать дополнительные аргументы (например, --incognito).

BROWSER и BROWSER_ARGS — это специальные переменные окружения, которые вы можете установить в файле .env для их настройки. См. пакет open для получения дополнительных сведений.

Пример:

export default defineConfig({
  server: {
    open: '/docs/index.html'
  }
})

server.proxy

Тип: Record<string, string | ProxyOptions>

Настройте пользовательские правила прокси для dev-сервера. Ожидает объект пар { ключ: опции }. Любые запросы, путь которых начинается с этого ключа, будут проксироваться на указанный целевой адрес. Если ключ начинается с ^, он будет интерпретироваться как RegExp. Опция configure может быть использована для доступа к экземпляру прокси. Если запрос соответствует какому-либо из настроенных правил прокси-сервера, он не будет преобразован Vite.

Обратите внимание, что если вы используете неотносительный base, вы должны префиксировать каждый ключ этим base.

Расширяет http-proxy-3. Дополнительные опции можно найти здесь.

В некоторых случаях вам также может понадобиться настроить основной dev-сервер (например, чтобы добавить пользовательские мидлвары в внутреннее приложение connect). Для этого вам нужно написать свой собственный плагин и использовать функцию configureServer.

Пример:

export default defineConfig({
  server: {
    proxy: {
      // сокращение строки:
      // http://localhost:5173/foo
      //   -> http://localhost:4567/foo
      '/foo': 'http://localhost:4567',
      // с параметрами:
      // http://localhost:5173/api/bar
      //   -> http://jsonplaceholder.typicode.com/bar
      '/api': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api/, '')
      },
      // с RegEx: http://localhost:5173/fallback/ -> http://jsonplaceholder.typicode.com/
      '^/fallback/.*': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/fallback/, '')
      },
      // Использование экземпляра прокси-сервера
      '/api': {
        target: 'http://jsonplaceholder.typicode.com',
        changeOrigin: true,
        configure: (proxy, options) => {
          // прокси будет представлять собой экземпляр 'http-proxy-3'
        }
      },
      // Проксирование веб-сокетов или socket.io:
      // ws://localhost:5173/socket.io
      //   -> ws://localhost:5174/socket.io
      // Будьте осторожны, используя "rewriteWsOrigin", так как это может оставить
      // проксирование открытым для атак CSRF.
      '/socket.io': {
        target: 'ws://localhost:5174',
        ws: true,
        rewriteWsOrigin: true
      }
    }
  }
})

server.cors

Тип: boolean | CorsOptions
По умолчанию: { origin: /^https?:\/\/(?:(?:[^:]+\.)?localhost|127\.0\.0\.1|\[::1\])(?::\d+)?$/ } (разрешает localhost, 127.0.0.1 и ::1)

Настройте CORS для dev-сервера. Передайте объект options, чтобы точно настроить поведение, или true, чтобы разрешить любой источник.

ОПАСНОСТЬ

Установка server.cors в значение true позволяет любому веб-сайту отправлять запросы на ваш сервер разработки и загружать ваш исходный код и контент. Мы рекомендуем всегда использовать явный список разрешённых источников.

server.headers

Тип: OutgoingHttpHeaders

Укажите заголовки ответов сервера.

server.hmr

Тип: boolean | { overlay?: boolean }

Отключите или настройте поведение HMR.

Установите server.hmr.overlay в false, чтобы отключить наложение ошибок сервера.

Устаревшие параметры

Параметры, связанные с WebSocket (protocol, host, port, path, clientPort, timeout, server), устарели. Вместо них используйте server.ws. Эти параметры автоматически синхронизируются, поэтому существующие конфигурации продолжат работать.

server.ws

Тип: false | { protocol?: string, host?: string, port?: number, path?: string, timeout?: number, clientPort?: number, server?: Server }

Настройте параметры подключения WebSocket. Установите значение false, чтобы полностью отключить подключение WebSocket.

protocol — протокол WebSocket (ws или wss)
host — хост сервера WebSocket
port — порт сервера WebSocket
path — путь WebSocket
clientPort — Переопределение порта на стороне клиента, позволяющее обслуживать websocket на другом порту, отличном от того, который ищет клиентский код
timeout — Таймаут подключения в миллисекундах (по умолчанию: 30000)
server — Использовать пользовательский HTTP-сервер для подключений WebSocket

Когда server.ws.server определён, Vite будет обрабатывать запросы на подключение WebSocket через предоставленный сервер. Если не в режиме мидлвара, Vite попытается обрабатывать запросы на подключение WebSocket через существующий сервер. Это может быть полезно при использовании самоподписанных сертификатов или когда вы хотите открыть Vite в сети на одном порту.

export default defineConfig({
  server: {
    ws: {
      protocol: 'wss',
      host: 'localhost',
      port: 3001,
    },
  },
})

Посмотрите vite-setup-catalogue для получения примеров.

ПРИМЕЧАНИЕ

С учётом конфигурации по умолчанию, обратные прокси перед Vite должны поддерживать проксирование WebSocket. Если клиент HMR Vite не может подключиться к WebSocket, клиент будет переключаться на прямое подключение к серверу HMR Vite, обходя обратные прокси:

Direct websocket connection fallback. Check out https://vite.dev/config/server-options.html#server-ws to remove the previous connection error.

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

настроить обратный прокси для проксирования WebSocket
установить server.strictPort = true и установить server.ws.clientPort на то же значение, что и server.port
установить server.ws.port на другое значение, отличное от server.port

server.forwardConsole

Тип: boolean | { unhandledErrors?: boolean, logLevels?: ('error' | 'warn' | 'info' | 'log' | 'debug')[] }
По умолчанию: автоопределение (true, если обнаружен AI-кодинговый агент с помощью пакета @vercel/detect-agent, в остальных случаях — false)

Перенаправляет события консоли браузера на консоль dev-сервера Vite во время разработки.

Значение true включает пересылку необработанных ошибок и вызовов console.error / console.warn.
Опция unhandledErrors управляет пересылкой необработанных исключений и необработанных отклонений промисов.
Опция logLevels определяет, какие методы console.* будут перенаправляться.

Пример:

export default defineConfig({
  server: {
    forwardConsole: {
      unhandledErrors: true,
      logLevels: ['warn', 'error'],
    },
  },
})

Когда необработанные ошибки перенаправляются, они выводятся в терминале сервера с улучшенным форматированием, например:

log

1:18:38 AM [vite] (client) [Unhandled error] Error: this is test error
 > testError src/main.ts:20:8
     18|
     19| function testError() {
     20|   throw new Error('this is test error')
       |        ^
     21| }
     22|
 > HTMLButtonElement.<anonymous> src/main.ts:6:2

server.warmup

Тип: { clientFiles?: string[], ssrFiles?: string[] }
Связано: Подготовка часто используемых файлов

Предварительно подготавливайте файлы для трансформации и кэшируйте результаты заранее. Это улучшает начальную загрузку страницы при запуске сервера и предотвращает каскадные преобразования.

clientFiles — это файлы, которые используются только на клиенте, в то время как ssrFiles — файлы, используемые только в SSR. Они принимают массив путей к файлам или шаблоны tinyglobby, относительные к root.

Убедитесь, что вы добавляете только те файлы, которые часто используются, чтобы не перегружать dev-сервер Vite при запуске.

export default defineConfig({
  server: {
    warmup: {
      clientFiles: ['./src/components/*.vue', './src/utils/big-utils.js'],
      ssrFiles: ['./src/server/modules/*.js']
    }
  }
})

server.watch

Тип: object | null

Опции для наблюдателя файловой системы, которые передаются в chokidar.

Наблюдатель сервера Vite следит за root и по умолчанию пропускает директории .git/, node_modules/, test-results/, а также cacheDir и build.outDir Vite. При обновлении отслеживаемого файла Vite применит HMR и обновит страницу только при необходимости.

Если установлено значение null, файлы не будут отслеживаться. server.watcher предоставит совместимый эмиттер событий, но вызовы add или unwatch не будут иметь эффекта.

Наблюдение за файлами в node_modules

В настоящее время невозможно отслеживать файлы и пакеты в node_modules. Для дальнейшего прогресса и обходных путей вы можете следить за проблемой #8619.

Использование Vite в Windows Subsystem for Linux (WSL) 2

При запуске Vite на WSL2 наблюдение за файловой системой не работает, когда файл редактируется приложениями Windows (процессами, не относящимися к WSL2). Это связано с ограничением WSL2. Это также относится к запуску на Docker с бэкендом WSL2.

Чтобы исправить это, вы можете:

Рекомендуется: Используйте приложения WSL2 для редактирования ваших файлов.
- Также рекомендуется переместить папку проекта за пределы файловой системы Windows. Доступ к файловой системе Windows из WSL2 медленный. Устранение этой накладной нагрузки улучшит производительность.
Установите { usePolling: true }.
- Обратите внимание, что usePolling приводит к высокой загрузке ЦП.

server.middlewareMode

Тип: boolean
По умолчанию: false

Создайте сервер Vite в режиме мидлвара.

Связано: appType, SSR - Настройка dev-сервера
Пример:

import express
 from 'express'
import { createServer
 as createViteServer
 } from 'vite'

async function createServer
() {
  const app
 = express
()

  // Создаём сервер Vite в режиме мидлвара
  const vite
 = await createViteServer
({
    server
: { middlewareMode
: true },
    // не включаем стандартные модули-мидлвары Vite для работы с HTML
    appType
: 'custom'
  })
  // Используем экземпляр connect в качестве мидлвара
  app
.use
(vite
.middlewares
)

  app
.use
('*', async (req
, res
) => {
    // Поскольку `appType` равен `'custom'`, здесь следует обслуживать ответ.
    // Примечание: если `appType` равен `'spa'` или `'mpa'`, Vite включает мидлваров
    // для обработки HTML-запросов и 404, поэтому пользовательские мидлвары должны
    // быть добавлены перед мидлварами Vite, чтобы они вступили в силу.
  })
}

createServer
()

server.fs.strict

Тип: boolean
По умолчанию: true (включено по умолчанию с версии Vite 2.7)

Ограничьте обслуживание файлов за пределами корня рабочего пространства.

server.fs.allow

Тип: string[]

Ограничьте файлы, которые могут быть обслужены через /@fs/. Когда server.fs.strict установлен в true, доступ к файлам за пределами этого списка директорий, которые не импортируются из разрешённого файла, приведёт к ошибке 403.

Можно указать как директории, так и файлы.

Vite будет искать корень потенциального рабочего пространства и использовать его по умолчанию. Действительное рабочее пространство должно соответствовать следующим условиям, в противном случае будет использован корень проекта:

содержит поле workspaces в package.json
содержит один из следующих файлов:
- lerna.json
- pnpm-workspace.yaml

Принимает путь для указания пользовательского корня рабочего пространства. Это может быть абсолютный путь или путь относительно корня проекта. Например:

export default defineConfig({
  server: {
    fs: {
      // Разрешаем обслуживать файлы с одного уровня до корня проекта
      allow: ['..']
    }
  }
})

Когда указано server.fs.allow, автоматическое определение корня рабочего пространства будет отключено. Для расширения оригинального поведения предоставлена утилита searchForWorkspaceRoot:

import { defineConfig, searchForWorkspaceRoot } from 'vite'

export default defineConfig({
  server: {
    fs: {
      allow: [
        // поиск корня рабочего пространства
        searchForWorkspaceRoot(process.cwd()),
        // ваши пользовательские правила
        '/path/to/custom/allow_directory',
        '/path/to/custom/allow_file.demo'
      ]
    }
  }
})

server.fs.deny

Тип: string[]
По умолчанию: ['.env', '.env.*', '*.{crt,pem,key,p12,pfx,cer,der}', '.npmrc', '.yarnrc.yml', '**/.git/**']

Чёрный список для чувствительных файлов, которые ограничены для обслуживания dev-сервером Vite. Этот список будет иметь более высокий приоритет, чем server.fs.allow. Поддерживаются шаблоны picomatch.

ПРИМЕЧАНИЕ

Этот чёрный список не применяется к директории public. Все файлы в этой директории обслуживаются без фильтрации, так как они копируются напрямую в выходную директорию во время сборки.

ПРИМЕЧАНИЕ

Фильтр запрета применяется к идентификатору модуля и к тому же идентификатору, но с удалёнными параметрами запроса. Поскольку плагин может читать файлы из любого места в своём хуке load (включая разрешение симлинков на запрещённые пути), Vite не может гарантировать, что запрещённый файл будет полностью недоступен через альтернативный путь. Если у вас есть альтернативный путь к этому файлу, добавьте его в список запрещённых путей тоже.

server.origin

Тип: string

Определяет источник сгенерированных URL-адресов ресурсов во время разработки.

export default defineConfig({
  server: {
    origin: 'http://127.0.0.1:8080'
  }
})

server.sourcemapIgnoreList

Тип: false | (sourcePath: string, sourcemapPath: string) => boolean
По умолчанию: (sourcePath) => sourcePath.includes('node_modules')

Определяет, следует ли игнорировать исходные файлы в sourcemap сервера, используемом для заполнения расширения sourcemap x_google_ignoreList.

server.sourcemapIgnoreList является эквивалентом build.rolldownOptions.output.sourcemapIgnoreList для dev-сервера. Разница между этими двумя параметрами конфигурации заключается в том, что функция rollup вызывается с относительным путём для sourcePath, в то время как server.sourcemapIgnoreList вызывается с абсолютным путём. В процессе разработки большинство модулей имеют карту и источник в одной папке, поэтому относительный путь для sourcePath — это само имя файла. В этих случаях использование абсолютных путей делает это более удобным.

По умолчанию исключаются все пути, содержащие node_modules. Вы можете передать false, чтобы отключить это поведение, или, для полного контроля, функцию, которая принимает путь к источнику и путь к sourcemap и возвращает, следует ли игнорировать путь к источнику.

export default defineConfig({
  server: {
    // Это значение по умолчанию, и оно добавит все файлы с `node_modules`
    // в их путях в список игнорируемых.
    sourcemapIgnoreList(sourcePath, sourcemapPath) {
      return sourcePath.includes('node_modules')
    }
  }
})

Примечание

server.sourcemapIgnoreList и build.rolldownOptions.output.sourcemapIgnoreList необходимо устанавливать независимо. server.sourcemapIgnoreList — это конфигурация только для сервера и не получает своего значения по умолчанию из определённых опций rollup.

Параметры сервера ​

server.host ​

server.allowedHosts ​

server.port ​

server.strictPort ​

server.https ​

server.open ​

server.proxy ​

server.cors ​

server.headers ​

server.hmr ​

server.ws ​

server.forwardConsole ​

server.warmup ​

server.watch ​

server.middlewareMode ​

server.fs.strict ​

server.fs.allow ​

server.fs.deny ​

server.origin ​

server.sourcemapIgnoreList ​

Параметры сервера

server.host

server.allowedHosts

server.port

server.strictPort

server.https

server.open

server.proxy

server.cors

server.headers

server.hmr

server.ws

server.forwardConsole

server.warmup

server.watch

server.middlewareMode

server.fs.strict

server.fs.allow

server.fs.deny

server.origin

server.sourcemapIgnoreList