Файловый вотчер и опции fs.watch

Параметр server.open в конфигурации Vite управляет автоматическим открытием браузера после запуска dev-сервера. По умолчанию после выполнения команды запуска Vite выводит URL локального сервера в терминал, но браузер не открывается автоматически. Настройка open изменяет это поведение.

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

import { defineConfig } from 'vite'

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

После запуска команды:

npm run dev

Vite автоматически откроет браузер с адресом локального сервера, например:

http://localhost:5173

Логика работы

Во время старта dev-сервера Vite:

  1. Определяет адрес сервера.
  2. Проверяет значение server.open.
  3. Если параметр активирован — вызывает системную команду открытия браузера.
  4. Передаёт URL операционной системе.

Механизм работает кроссплатформенно:

  • Windows
  • Linux
  • macOS

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

Типы значений

Параметр поддерживает два основных варианта:

open?: boolean | string

Значение true

Открывает корневой адрес проекта.

server: {
  open: true
}

Результат:

http://localhost:5173/

Значение false

Полностью отключает автоматическое открытие.

server: {
  open: false
}

Это поведение используется по умолчанию.

Строковое значение

Позволяет открыть конкретный путь внутри приложения.

server: {
  open: '/admin'
}

После запуска откроется:

http://localhost:5173/admin

Это особенно удобно при разработке:

  • административных панелей;
  • отдельных страниц;
  • демонстрационных модулей;
  • Storybook-подобных интерфейсов;
  • SPA с несколькими зонами.

Открытие вложенных маршрутов

Vite не проверяет существование маршрута. Он просто добавляет путь к базовому URL.

Пример:

server: {
  open: '/dashboard/users'
}

Будет открыт адрес:

http://localhost:5173/dashboard/users

Если приложение использует клиентский роутинг:

  • Vue Router
  • React Router
  • SvelteKit Router

то переход обработается уже внутри SPA.

Работа с base

Если используется параметр base, итоговый URL строится с его учётом.

Пример:

export default defineConfig({
  base: '/app/',
  server: {
    open: true
  }
})

Откроется:

http://localhost:5173/app/

Если указать строковый путь:

server: {
  open: '/profile'
}

Результат:

http://localhost:5173/app/profile

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

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

Пример:

export default defineConfig({
  server: {
    port: 3001,
    open: '/admin'
  }
})

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

Условное открытие браузера

Часто возникает необходимость включать открытие браузера только в локальной среде.

Пример:

import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    open: process.env.NODE_ENV !== 'production'
  }
})

Использование с режимами Vite

Параметр можно комбинировать с режимами (mode).

import { defineConfig } from 'vite'

export default defineConfig(({ mode }) => {
  return {
    server: {
      open: mode === 'development'
    }
  }
})

Работа через переменные окружения

Пример:

VITE_OPEN_BROWSER=true

Конфигурация:

export default defineConfig({
  server: {
    open: process.env.VITE_OPEN_BROWSER === 'true'
  }
})

Поведение при запуске через Docker

В контейнерах Docker автоматическое открытие браузера обычно бесполезно, поскольку контейнер не имеет доступа к GUI-хосту.

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

server: {
  open: process.env.DOCKER !== 'true'
}

Поведение в WSL

В Windows Subsystem for Linux возможны особенности:

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

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

server: {
  open: false
}

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

При включённом HTTPS откроется защищённый URL.

Пример:

server: {
  https: true,
  open: true
}

Результат:

https://localhost:5173

Если сертификат самоподписанный, браузер может показать предупреждение безопасности.

Совместимость с HMR

Параметр open никак не влияет на:

  • Hot Module Replacement;
  • WebSocket;
  • обновление модулей;
  • производительность сервера.

Он выполняется только один раз — во время старта dev-сервера.

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

Если указан host, браузер откроет именно этот адрес.

Пример:

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

В большинстве случаев будет открыт:

http://localhost:5173

Но поведение может отличаться в зависимости от ОС.

Если указан конкретный IP:

server: {
  host: '192.168.0.15',
  open: true
}

Откроется:

http://192.168.0.15:5173

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

server: {
  port: 8080,
  open: true
}

Результат:

http://localhost:8080

Поведение при занятом порте

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

Пример:

server: {
  port: 3000,
  open: true
}

Если 3000 занят:

http://localhost:3001

Браузер откроет именно фактически используемый порт.

Использование в связке с backend-framework

Во многих проектах Vite используется как frontend-сервер рядом с backend-приложением:

  • Laravel
  • Symfony
  • Express
  • NestJS
  • Django
  • ASP.NET

Часто требуется открывать не корень Vite, а конкретный backend-маршрут.

Пример:

server: {
  open: '/login'
}

Автоматическое открытие панели администратора

Типичный сценарий:

server: {
  open: '/admin'
}

или:

server: {
  open: '/dashboard'
}

Это экономит время при постоянной разработке одной области приложения.

Открытие документации

Vite может автоматически открывать встроенную документацию проекта.

Пример:

server: {
  open: '/docs'
}

Различия между CLI и конфигурацией

Открытие браузера можно включать не только через vite.config.js, но и через CLI.

Пример:

vite --open

или:

npm run dev -- --open

Эквивалентно:

server: {
  open: true
}

Передача пути через CLI

CLI также поддерживает указание пути.

Пример:

vite --open /admin

Использование в package.json

Пример:

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

или:

{
  "scripts": {
    "dev": "vite --open /admin"
  }
}

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

Если одновременно используются:

  • CLI-флаги;
  • конфигурационный файл;
  • API Vite;

приоритет обычно имеет CLI.

Пример:

vite --open=false

может переопределить:

server: {
  open: true
}

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

Vite можно запускать программно.

Пример:

import { createServer } from 'vite'

async function start() {
  const server = await createServer({
    server: {
      open: true
    }
  })

  await server.listen()
}

start()

Ограничения параметра

server.open:

  • не гарантирует успешное открытие браузера;
  • зависит от системных утилит ОС;
  • может не работать в headless-средах;
  • не предназначен для production.

Типичные проблемы

Браузер не открывается

Причины:

  • headless Linux;
  • Docker;
  • SSH-сессия;
  • WSL;
  • отсутствие GUI;
  • системные ограничения.

Открывается неправильный браузер

Vite использует браузер по умолчанию в системе. Настройка конкретного браузера напрямую через server.open отсутствует.

Открывается несколько вкладок

Это происходит, если dev-сервер перезапускается:

  • при изменении конфигурации;
  • после падения процесса;
  • при использовании watcher-инструментов.

Практические сценарии

React SPA

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

Панель администратора

export default defineConfig({
  server: {
    open: '/admin'
  }
})

Мобильная разработка

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

Браузер на хост-машине не открывается, а приложение тестируется с телефона по локальной сети.

Корпоративная разработка

export default defineConfig(({ mode }) => ({
  server: {
    open: mode === 'local'
  }
}))

Рекомендации по использованию

Автоматическое открытие браузера удобно:

  • в одиночной разработке;
  • при частых перезапусках;
  • для frontend-проектов;
  • при работе с административными интерфейсами.

Отключение open предпочтительно:

  • в Docker;
  • на CI/CD;
  • на удалённых серверах;
  • в headless-средах;
  • при запуске нескольких dev-серверов одновременно.
Оглавление