Опции server: host, port, strictPort

Раздел server в конфигурации Vite управляет поведением dev-сервера во время разработки. Через него настраиваются сетевые параметры, адрес прослушивания, порт, политика запуска и особенности локального окружения.

Наиболее часто используемые параметры:

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    host: 'localhost',
    port: 5173,
    strictPort: false
  }
})

Эти настройки напрямую влияют на способ подключения браузера к dev-серверу, работу в локальной сети, использование Docker, WSL, виртуальных машин и поведение при конфликте портов.

Опция host

Параметр host определяет сетевой интерфейс, на котором запускается dev-сервер.

По умолчанию:

server: {
  host: 'localhost'
}

Это означает, что сервер доступен только внутри текущей машины.

Работа через localhost

Наиболее распространённый сценарий:

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

Приложение будет доступно по адресу:

http://localhost:5173

или:

http://127.0.0.1:5173

Такой режим безопасен и удобен для обычной локальной разработки.

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

Для доступа к приложению из локальной сети используется:

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

или сокращённая запись:

export default defineConfig({
  server: {
    host: true
  }
})

Теперь сервер принимает подключения со всех сетевых интерфейсов.

Например:

http://192.168.1.10:5173

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

  • тестировании на смартфонах;
  • работе в Docker;
  • использовании WSL;
  • запуске внутри виртуальной машины;
  • работе через удалённые контейнеры;
  • использовании LAN-режима.

Проверка IP-адреса

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

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

Строка Network появляется только при включённом host.

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

Можно указать определённый сетевой интерфейс:

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

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

Такой подход используется редко, но бывает полезен при:

  • сложной сетевой конфигурации;
  • нескольких интерфейсах;
  • тестировании VPN;
  • ограничении доступа.

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

На разных ОС localhost может резолвиться по-разному:

127.0.0.1
::1

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

  • WebSocket;
  • HMR;
  • Docker;
  • IPv6;
  • reverse proxy.

В таких случаях часто помогает:

host: '127.0.0.1'

вместо:

host: 'localhost'

Работа в Docker

В контейнерах dev-сервер должен слушать внешний интерфейс:

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

Иначе приложение внутри контейнера будет недоступно снаружи.

Типичный пример:

services:
  app:
    ports:
      - "5173:5173"

Без host: '0.0.0.0' проброс порта часто не работает корректно.

Работа в WSL

Подсистема Linux в Windows также требует внешнего интерфейса:

server: {
  host: '0.0.0.0'
}

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

Опция port

Параметр port задаёт номер TCP-порта dev-сервера.

Пример:

export default defineConfig({
  server: {
    port: 3000
  }
})

Теперь сервер будет запускаться по адресу:

http://localhost:3000

Порт по умолчанию

По умолчанию Vite использует:

5173

Если порт свободен, сервер стартует именно на нём.

Автоматический поиск свободного порта

Если указанный порт занят:

server: {
  port: 3000
}

Vite автоматически попытается найти следующий свободный:

3000 → 3001 → 3002 → ...

Например:

Port 3000 is in use, trying another one...

После чего сервер может стартовать на:

http://localhost:3001

Почему это важно

Автоматическая смена порта удобна, но иногда создаёт проблемы:

  • frontend ожидает конкретный адрес;
  • backend настроен на фиксированный origin;
  • OAuth использует жёсткий callback URL;
  • Docker-проброс рассчитан на один порт;
  • прокси ожидает строго определённый endpoint;
  • мобильное тестирование использует сохранённый адрес.

В таких случаях требуется фиксированный порт.

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

Часто разные проекты запускаются на разных портах:

// проект 1
server: {
  port: 3000
}
// проект 2
server: {
  port: 4000
}
// проект 3
server: {
  port: 5173
}

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

Типичные порты frontend-разработки

Инструмент Порт
Vite 5173
React старый dev server 3000
Vue CLI 8080
Angular 4200
Next.js 3000

Опция strictPort

Параметр strictPort управляет поведением при занятом порте.

По умолчанию:

strictPort: false

Это означает автоматический поиск следующего свободного порта.

Режим строгого порта

При включении:

export default defineConfig({
  server: {
    port: 3000,
    strictPort: true
  }
})

Vite больше не будет искать свободный порт.

Если 3000 занят:

Error: Port 3000 is already in use

Сервер завершит запуск с ошибкой.

Когда нужен strictPort

Backend ожидает фиксированный origin

Например:

http://localhost:3000

Если Vite автоматически переключится на 3001, backend может перестать принимать запросы.

OAuth и авторизация

Многие OAuth-провайдеры используют фиксированный callback URL:

http://localhost:3000/callback

Изменение порта ломает авторизацию.

Docker и reverse proxy

Прокси может быть настроен только на один порт:

proxy_pass http://frontend:3000;

Автоматическая смена порта делает конфигурацию недействительной.

E2E-тестирование

Автотесты часто ожидают конкретный адрес:

http://localhost:3000

При смене порта тесты перестают работать.

Практический пример

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    host: '0.0.0.0',
    port: 3000,
    strictPort: true
  }
})

Конфигурация означает:

  • сервер доступен по сети;
  • используется порт 3000;
  • при конфликте запуск завершится ошибкой.

Поведение при конфликте порта

strictPort: false

server: {
  port: 3000
}

Результат:

3000 занят
→ Vite запускается на 3001

strictPort: true

server: {
  port: 3000,
  strictPort: true
}

Результат:

3000 занят
→ ошибка запуска

Проверка занятого порта

Linux/macOS:

lsof -i :3000

Windows:

netstat -ano | findstr :3000

Завершение процесса

Linux/macOS:

kill -9 PID

Windows:

taskkill /PID 1234 /F

Комбинирование параметров

Наиболее распространённая production-like конфигурация разработки:

export default defineConfig({
  server: {
    host: '0.0.0.0',
    port: 3000,
    strictPort: true
  }
})

Подходит для:

  • Docker;
  • микросервисов;
  • reverse proxy;
  • fullstack-приложений;
  • мобильного тестирования;
  • командной разработки.

Использование через CLI

Все параметры можно переопределять из командной строки.

Указание порта

vite --port 4000

Включение внешнего host

vite --host

Указание IP

vite --host 0.0.0.0

Строгий порт

vite --strictPort

Приоритет конфигурации

CLI-параметры имеют более высокий приоритет:

vite --port 4000

Даже если в конфигурации указано:

server: {
  port: 3000
}

будет использован:

4000

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

{
  "scripts": {
    "dev": "vite --host --port 3000 --strictPort"
  }
}

Использование переменных окружения

export default defineConfig({
  server: {
    port: Number(process.env.PORT) || 3000
  }
})

Пример:

PORT=4000 npm run dev

Типичная конфигурация для команды

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    host: true,
    port: 3000,
    strictPort: true
  }
})

Такая конфигурация обеспечивает:

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