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

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

В конфигурации Vite параметр задаётся через build.base (или base на верхнем уровне конфигурации, так как он применим и к dev-серверу):

// vite.config.js
export default {
  base: '/app/'
}

Роль base в процессе сборки

При выполнении production-сборки Vite анализирует значение base и использует его для:

  • генерации путей к JavaScript-бандлам
  • формирования ссылок на CSS-файлы
  • корректного подключения статических ресурсов из public
  • настройки import.meta.env.BASE_URL
  • обработки динамических импортов

Если приложение размещается не в корне домена, например:

https://example.com/my-vite-app/

то значение base должно соответствовать подкаталогу:

export default {
  base: '/my-vite-app/'
}

Без корректной настройки приложение будет пытаться загружать ресурсы из корня домена:

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

вместо:

https://example.com/my-vite-app/assets/index.js   ✔

Значение по умолчанию

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

base: '/'

Это означает, что приложение ожидается в корне домена. Такой вариант корректен для большинства SPA, размещённых на:

  • root-домене
  • корневом пути поддоменов

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

Для сценариев, когда приложение может быть развернуто в разных окружениях без жёсткого фиксирования пути, используется относительное значение:

export default {
  base: './'
}

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

Особенности поведения:

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

Связь base и import.meta.env.BASE_URL

Vite автоматически прокидывает значение base в переменную окружения:

import.meta.env.BASE_URL

Эта переменная используется для построения путей к ресурсам внутри приложения:

const imageUrl = `${import.meta.env.BASE_URL}images/logo.png`

Если base задан как:

base: '/my-vite-app/'

то BASE_URL будет равен:

/my-vite-app/

Это позволяет унифицировать доступ к статическим ресурсам без хардкода путей.

Влияние base на public директорию

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

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

public/
  logo.png

При конфигурации:

base: '/app/'

доступ к ресурсу будет:

/app/logo.png

При base: '/':

/logo.png

base и динамические импорты

Vite разбивает код на чанки и формирует динамические импорты с учётом базового пути:

const module = await import('./features/dashboard.js')

В production результатом будет загрузка чанка по пути:

/my-vite-app/assets/dashboard.[hash].js

если base задан как /my-vite-app/.

При неверной настройке base возможны ошибки:

  • 404 при загрузке чанков
  • некорректная работа lazy-loading
  • сбои при SSR-гидрации

Развёртывание в подкаталоге

Наиболее частый кейс использования base — деплой в подкаталогах серверов:

Nginx

server {
  location /admin/ {
    root /var/www/app;
  }
}

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

export default {
  base: '/admin/'
}

Apache

https://domain.com/project/
export default {
  base: '/project/'
}

CDN и base

При использовании CDN важно учитывать, что base может включать абсолютный URL:

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

В этом случае все ассеты будут загружаться напрямую с CDN:

https://cdn.example.com/assets/index-abc123.js

Такой подход используется для:

  • ускорения загрузки
  • разделения инфраструктуры
  • кеширования статики

Особенности работы с hash-ассетами

Vite по умолчанию добавляет хеши к именам файлов:

assets/index.8d7f3a2c.js

base добавляется перед этим путём:

/app/assets/index.8d7f3a2c.js

Таким образом base не влияет на структуру файлов, но полностью управляет их корневым размещением.

Ошибки неправильной настройки base

Некорректное значение base приводит к типовым проблемам:

1. Белый экран при загрузке

Причина — не найден основной JS-бандл из-за неверного пути.

2. 404 на ассеты

GET /assets/index.js 404

3. Поломка роутинга SPA

History API требует согласованности между:

  • серверным маршрутом
  • base
  • router base (например, Vue Router)

Согласование base и router

При использовании клиентского роутера необходимо синхронизировать base:

import { createRouter, createWebHistory } from 'vue-router'

const router = createRouter({
  history: createWebHistory(import.meta.env.BASE_URL),
  routes: []
})

Если этого не сделать:

  • маршруты будут начинаться с /
  • при размещении в подкаталоге навигация сломается

base в мульти-приложениях

При монорепозиториях или нескольких Vite-приложениях на одном домене используется различный base:

/admin/
/shop/
/docs/

Каждое приложение собирается отдельно:

export default {
  base: '/admin/'
}
export default {
  base: '/shop/'
}

Это позволяет изолировать сборки и избежать конфликтов ассетов.

Динамическое определение base

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

export default {
  base: process.env.VITE_BASE_PATH
}

или:

export default ({ mode }) => ({
  base: mode === 'production' ? '/app/' : '/'
})

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

Влияние base на HTML entry point

Сгенерированный index.html содержит ссылки вида:

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

или:

<script type="module" src="./assets/index.js"></script>

в зависимости от конфигурации.

Это делает base критически важным для корректной загрузки entry point приложения.

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

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

final_url = base + asset_path

Где:

  • asset_path — путь, сгенерированный Vite
  • base — конфигурационный префикс

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

Совместимость с legacy-развёртываниями

При интеграции Vite в существующие системы:

  • CMS
  • legacy PHP-приложения
  • корпоративные порталы

base становится ключевым параметром интеграции, так как определяет, где именно будет “жить” фронтенд внутри общей структуры URL.

В таких сценариях часто встречаются конфигурации:

base: '/bitrix/components/frontend/'

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

Оглавление