Импорт JSON-файлов

Параметр server.host управляет адресом, на котором Vite запускает dev-сервер. От этой настройки зависит, будет ли приложение доступно только локально, из локальной сети, внутри Docker-контейнера, через виртуальную машину, прокси-сервер или внешний туннель.

По умолчанию Vite запускается только на localhost, что обеспечивает безопасную локальную разработку, но ограничивает доступ извне.

Базовый пример:

import { defineConfig } from 'vite'

export default defineConfig({
    server: {
        host: 'localhost'
    }
})

Значение localhost

Наиболее распространённый вариант.

server: {
    host: 'localhost'
}

При таком режиме:

  • приложение открывается только на текущем компьютере;
  • доступ по локальной сети отсутствует;
  • другие устройства не смогут подключиться;
  • браузер использует loopback-интерфейс.

Обычно сервер становится доступен по адресу:

http://localhost:5173

или:

http://127.0.0.1:5173

Особенности localhost

В разных ОС и сетевых конфигурациях localhost может резолвиться:

  • в IPv4:
127.0.0.1
  • либо в IPv6:
::1

Иногда это вызывает проблемы:

  • HMR не подключается;
  • браузер открывает неправильный адрес;
  • внутри Docker соединение отсутствует;
  • мобильные устройства не видят сервер.

В подобных случаях используют явный IP-адрес.

Значение 0.0.0.0

Наиболее важный режим для сетевого доступа.

server: {
    host: '0.0.0.0'
}

Такой сервер начинает слушать все сетевые интерфейсы:

  • localhost;
  • локальную сеть;
  • Docker bridge;
  • виртуальные интерфейсы;
  • VPN;
  • WSL;
  • туннели.

После запуска Vite обычно показывает несколько адресов:

Local:   http://localhost:5173/
Network: http://192.168.1.10:5173/

Практическое применение

Доступ с телефона

server: {
    host: '0.0.0.0'
}

После этого приложение можно открыть с мобильного устройства:

http://192.168.1.10:5173

Это особенно важно при:

  • тестировании адаптивности;
  • проверке touch-событий;
  • отладке Safari iOS;
  • тестировании PWA;
  • проверке WebView.

Работа внутри Docker

Без 0.0.0.0 контейнер часто недоступен извне.

Правильная конфигурация:

server: {
    host: '0.0.0.0'
}

Docker:

ports:
  - "5173:5173"

Если оставить localhost, Vite будет слушать только внутри контейнера.

WSL2

Для Windows Subsystem for Linux также почти всегда используется:

server: {
    host: '0.0.0.0'
}

Иначе Windows-браузер может не получить доступ к Linux-серверу.

Использование конкретного IP

Vite позволяет указать конкретный сетевой интерфейс.

Пример:

server: {
    host: '192.168.0.15'
}

В этом случае сервер будет доступен только через указанный IP.

Когда это полезно

Несколько сетевых интерфейсов

Например:

  • Ethernet;
  • Wi-Fi;
  • VPN;
  • Docker;
  • Hyper-V.

Указание конкретного IP помогает избежать конфликтов.

Ограничение доступа

Можно запретить подключение через другие интерфейсы.

Например:

server: {
    host: '127.0.0.1'
}

или:

server: {
    host: '192.168.1.50'
}

Значение true

Vite поддерживает специальное сокращение:

server: {
    host: true
}

Эквивалент:

host: '0.0.0.0'

Однако строковый вариант обычно считается более читаемым.

Использование IPv6

Vite умеет работать с IPv6-адресами.

Пример:

server: {
    host: '::'
}

или:

server: {
    host: '::1'
}

Разница

::1

IPv6-аналог localhost.

::

IPv6-аналог 0.0.0.0.

Влияние на HMR

server.host напрямую влияет на работу Hot Module Replacement.

Если HMR не может подключиться к websocket-серверу:

  • обновления перестают применяться;
  • браузер постоянно перезагружается;
  • появляется ошибка websocket connection failed.

Типичная проблема:

WebSocket connection failed

Причина:

  • браузер подключается по одному адресу;
  • websocket пытается использовать другой.

Связь с server.hmr.host

Иногда необходимо отдельно указать host для HMR.

Пример:

export default defineConfig({
    server: {
        host: '0.0.0.0',
        hmr: {
            host: 'localhost'
        }
    }
})

Это особенно важно:

  • за reverse proxy;
  • в Docker;
  • при HTTPS;
  • через Cloudflare Tunnel;
  • через ngrok;
  • внутри Kubernetes.

Использование с HTTPS

При HTTPS настройка host становится особенно важной.

Пример:

server: {
    host: '0.0.0.0',
    https: true
}

Если сертификат выписан на конкретный домен:

server: {
    host: 'dev.example.local',
    https: {
        key: fs.readFileSync('./cert.key'),
        cert: fs.readFileSync('./cert.crt')
    }
}

Работа через reverse proxy

Например:

  • Nginx;
  • Traefik;
  • Caddy;
  • Apache.

Vite часто запускается так:

server: {
    host: '0.0.0.0'
}

А внешний сервер проксирует запросы.

Пример Nginx:

location / {
    proxy_pass http://127.0.0.1:5173;
}

Использование в monorepo

В monorepo dev-сервер может запускаться:

  • внутри workspace;
  • внутри контейнера;
  • на удалённой машине.

В таких случаях localhost часто вызывает проблемы.

Наиболее универсальный вариант:

server: {
    host: '0.0.0.0'
}

Настройка через CLI

Параметр можно указать без изменения конфигурации.

Локальный host

vite --host localhost

Все интерфейсы

vite --host 0.0.0.0

Конкретный IP

vite --host 192.168.1.15

Использование в npm scripts

{
  "scripts": {
    "dev": "vite --host"
  }
}

Сокращённый вариант --host без значения автоматически включает режим:

0.0.0.0

Переменные окружения

Иногда host выносится в environment-конфигурацию.

Пример:

VITE_HOST=0.0.0.0
server: {
    host: process.env.VITE_HOST
}

Типичные ошибки

Сервер недоступен с телефона

Причина:

host: 'localhost'

Решение:

host: '0.0.0.0'

Docker не пробрасывает сервер

Причина:

Vite слушает loopback внутри контейнера.

Решение:

host: '0.0.0.0'

HMR перестал работать

Причины:

  • websocket использует неправильный адрес;
  • reverse proxy режет websocket;
  • IPv6/IPv4 конфликт.

Решение:

server: {
    host: '0.0.0.0',
    hmr: {
        host: 'localhost'
    }
}

EADDRNOTAVAIL

Ошибка:

EADDRNOTAVAIL

Причина:

указан IP, отсутствующий на машине.

Например:

host: '192.168.1.200'

при отсутствии такого интерфейса.

EACCES

Ошибка:

EACCES permission denied

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

server: {
    host: '0.0.0.0',
    port: 80
}

Порт 80 требует повышенных привилегий.

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

Windows

ipconfig

Linux

ip addr

macOS

ifconfig

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

Режим:

host: '0.0.0.0'

делает dev-сервер доступным извне.

Это означает:

  • любой пользователь локальной сети может открыть приложение;
  • возможен доступ к исходным sourcemaps;
  • доступны dev-инструменты;
  • иногда раскрываются переменные окружения.

Для публичных сетей такой режим нежелателен.

Рекомендуемые конфигурации

Обычная локальная разработка

server: {
    host: 'localhost'
}

Работа с мобильными устройствами

server: {
    host: '0.0.0.0'
}

Docker

server: {
    host: '0.0.0.0'
}

WSL2

server: {
    host: '0.0.0.0'
}

Reverse proxy

server: {
    host: '0.0.0.0',
    hmr: {
        host: 'dev.local'
    }
}

Полная конфигурация

import { defineConfig } from 'vite'
import fs from 'fs'

export default defineConfig({
    server: {
        host: '0.0.0.0',
        port: 5173,
        strictPort: true,

        https: {
            key: fs.readFileSync('./ssl/dev.key'),
            cert: fs.readFileSync('./ssl/dev.crt')
        },

        hmr: {
            protocol: 'wss',
            host: 'dev.local',
            port: 5173
        }
    }
})

Такая конфигурация подходит для:

  • Docker;
  • HTTPS;
  • reverse proxy;
  • локальной сети;
  • тестирования с мобильных устройств;
  • корпоративной разработки;
  • сложной сетевой инфраструктуры.
Оглавление