Базовый путь через base

base в конфигурации Vite определяет базовый публичный путь, с которого приложение будет обслуживаться в продакшене. Это значение влияет на генерацию URL для всех ресурсов: JavaScript-бандлов, CSS, изображений и любых файлов, подключаемых через систему сборки.

В типичном сценарии разработки приложение запускается в корне домена (/). Однако при деплое на подкаталог, например https://example.com/app/, требуется корректно указать базовый путь, иначе ресурсы будут запрашиваться с неверных URL и приложение не загрузится.

Конфигурация base в vite.config.js

Основная точка настройки — объект конфигурации Vite:

import { defineConfig } from 'vite'

export default defineConfig({
  base: '/app/'
})

Значение base должно заканчиваться и начинаться с /, если это относительный путь. Такой формат гарантирует корректную генерацию ссылок на ресурсы.

Поведение по умолчанию

Если base не указан, используется значение:

/

Это означает, что приложение ожидается в корне домена. Все ассеты будут строиться относительно /, например:

/assets/index-abc123.js
/assets/style-def456.css

При смене базового пути структура URL меняется автоматически.

Как base влияет на сборку

Во время выполнения vite build происходит подстановка значения base во все места, где формируются публичные URL.

Примеры влияния:

  • пути к скриптам в index.html
  • ссылки на динамически импортируемые модули
  • URL статики из public
  • обработка import.meta.env.BASE_URL

Если указано:

base: '/my-app/'

то результат сборки будет содержать:

<script type="module" src="/my-app/assets/index-xxx.js"></script>

Связь с import.meta.env.BASE_URL

Vite автоматически предоставляет переменную:

import.meta.env.BASE_URL

Она всегда соответствует значению base.

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

const logoUrl = `${import.meta.env.BASE_URL}logo.png`

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

Размещение приложения в подкаталоге

Типичный сценарий — деплой в подпапку на сервере или хостинге.

Пример структуры:

https://example.com/blog/

В этом случае конфигурация должна быть:

export default defineConfig({
  base: '/blog/'
})

Иначе браузер будет пытаться загрузить:

https://example.com/assets/index.js

вместо:

https://example.com/blog/assets/index.js

Использование относительного базового пути

Vite поддерживает относительное значение:

base: './'

Такой вариант полезен при:

  • локальном открытии index.html без сервера
  • статических сборках, которые могут перемещаться между директориями
  • некоторых сценариях Electron или file-based приложений

В этом режиме ресурсы подключаются относительно текущего HTML-файла:

./assets/index.js

Интеграция с public директорией

Файлы из папки public копируются без обработки и доступны напрямую через base.

Пример:

public/logo.png

При:

base: '/app/'

URL будет:

/app/logo.png

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

Динамические сценарии и CDN

При использовании CDN значение base часто указывает на внешний домен или путь CDN:

export default defineConfig({
  base: 'https://cdn.example.com/assets/'
})

В этом случае:

  • все ассеты загружаются с CDN
  • HTML содержит абсолютные ссылки
  • приложение полностью отделяется от основного сервера

Типичные ошибки при настройке base

Неправильные значения приводят к проблемам загрузки:

1. Отсутствие завершающего слэша

base: '/app'

может привести к некорректной сборке URL:

/appassets/index.js

2. Несоответствие пути деплоя

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

3. Смешивание абсолютных и относительных путей

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

Взаимодействие base и роутеров

При использовании клиентских роутеров (например, history mode) значение base часто должно совпадать с базовым маршрутом:

  • /app/ для Vue Router или React Router (history)
  • /admin/ для административных панелей

Несоответствие приводит к 404 при обновлении страницы.

Влияние на index.html

Vite использует index.html как часть графа сборки. Все пути внутри него также переписываются относительно base.

Пример:

<script type="module" src="/main.js"></script>

После сборки с:

base: '/panel/'

становится:

<script type="module" src="/panel/assets/main-xxx.js"></script>

Использование base в multi-app структуре

При наличии нескольких приложений в одном домене:

/site/
/admin/
/dashboard/

каждое приложение требует собственного base:

base: '/site/'
base: '/admin/'
base: '/dashboard/'

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

Поведение при разработке (vite dev)

В режиме разработки base почти не влияет на поведение сервера, так как Vite использует виртуальный dev-server.

Однако import.meta.env.BASE_URL уже принимает значение base, что важно для логики приложения даже в dev-режиме.

Работа с относительными импортами и base

base не влияет на:

  • import в JavaScript модулях
  • абсолютные импорты через alias (@/)
  • внутренние пути модулей

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

Совместимость с legacy-браузерами и сборками

При использовании @vitejs/plugin-legacy значение base также применяется к legacy-бандлам. Это гарантирует единообразие путей для современных и старых браузеров.

Практическая модель работы base

Логика работы можно представить так:

  1. Определяется base из конфигурации
  2. Все публичные URL получают этот префикс
  3. Сборщик переписывает ссылки в index.html
  4. import.meta.env.BASE_URL синхронизируется
  5. Dev-server имитирует поведение без физического префикса

Значение base в архитектуре приложения

base фактически определяет точку монтирования приложения в структуре сайта. Это не просто строка конфигурации, а ключевой параметр, влияющий на:

  • переносимость сборки между окружениями
  • корректность загрузки ресурсов
  • работу роутинга
  • интеграцию с CDN и прокси-серверами
  • стабильность деплоя в подкаталоги
Оглавление