Настройка директории вывода через build.assetsDir

build.assetsDir — это параметр конфигурации Vite, отвечающий за директорию внутри итоговой сборки, в которую помещаются все ассеты: изображения, шрифты, медиафайлы и другие ресурсы, импортируемые из кода. По умолчанию Vite размещает такие файлы в папке assets внутри каталога сборки dist, но это поведение можно изменить под особенности проекта, CDN-структуру или требования backend-интеграции.

При выполнении production-сборки Vite формирует каталог dist, внутри которого оказываются:

  • JavaScript-бандлы
  • CSS-файлы
  • статические ассеты (изображения, шрифты, иконки, медиа)

Параметр assetsDir управляет именно тем, в какую подпапку будут помещены файлы ассетов, на которые ссылается код через import или URL-обработку Vite.

Стандартное значение:

// vite.config.js
export default {
  build: {
    assetsDir: 'assets'
  }
}

При таком конфиге структура будет следующей:

dist/
  assets/
    logo.8d7f3a.png
    font.a1b2c3.woff2
    background.c9d0e1.jpg
  index.html
  index.8f3a1c.js
  index.7b2c9d.css

Механизм работы assetsDir внутри пайплайна Vite

Vite использует Rollup как основу для сборки. В процессе компиляции:

  1. Импорты ассетов анализируются (import img from ‘./img.png’)
  2. Файлы копируются в итоговый output
  3. Генерируются хешированные имена для кеширования
  4. Формируется структура каталогов внутри dist

Параметр assetsDir влияет только на шаг размещения итоговых файлов, не затрагивая:

  • генерацию хешей
  • оптимизацию изображений
  • инлайнинг через base64 (если активирован assetsInlineLimit)

Изменение директории assetsDir

Директория может быть изменена для адаптации к структуре сервера или CDN:

export default {
  build: {
    assetsDir: 'static'
  }
}

Результат:

dist/
  static/
    logo.8d7f3a.png
    font.a1b2c3.woff2
  index.html
  index.js

Такой подход часто используется, если сервер ожидает статические ресурсы в отдельной директории, например /static.

Влияние на пути в итоговом HTML

Важно учитывать, что assetsDir не влияет напрямую на логику подключения ресурсов в коде. Vite автоматически пересчитывает пути в HTML и CSS.

Например:

import logo from './logo.png'

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

<img src="/static/logo.8d7f3a.png">

или при стандартном значении:

<img src="/assets/logo.8d7f3a.png">

Фактический URL формируется на основе сочетания:

  • build.assetsDir
  • build.assetsInlineLimit
  • build.outDir
  • base

Взаимодействие с base и publicPath-логикой

Параметр assetsDir работает совместно с base, который задаёт корневой публичный путь приложения.

export default {
  base: '/app/',
  build: {
    assetsDir: 'assets'
  }
}

В этом случае итоговые URL будут:

/app/assets/logo.8d7f3a.png

Это особенно важно при деплое в подкаталоги или на GitHub Pages, где приложение не находится в корне домена.

Отличие assetsDir от publicDir

Частая ошибка — смешивание assetsDir и publicDir.

publicDir:

  • файлы копируются как есть
  • не проходят через pipeline Vite
  • не получают хешей
  • доступны по фиксированным URL

assetsDir:

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

Пример:

public/logo.png  →  dist/logo.png
src/logo.png     →  dist/assets/logo.8d7f3a.png

Использование нестандартной структуры для интеграции с backend

В проектах с PHP, Bitrix или другими серверными системами часто требуется особая структура:

export default {
  build: {
    assetsDir: 'bitrix-assets'
  }
}

Результат:

dist/
  bitrix-assets/
    app.1a2b3c.js
    style.4d5e6f.css

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

Влияние на кеширование и производительность

Поскольку assetsDir влияет только на путь, но не на имена файлов, ключевую роль в кешировании играют:

  • хеши в именах файлов
  • HTTP cache headers на сервере
  • CDN конфигурация

Пример итогового файла:

assets/logo.9f3a1c2d.png

Даже при изменении assetsDir:

static/logo.9f3a1c2d.png

Хеш остаётся стабильным, что гарантирует корректное кеширование.

Связь с rollupOptions.output.assetFileNames

В некоторых случаях требуется более тонкая настройка структуры:

export default {
  build: {
    assetsDir: 'assets',
    rollupOptions: {
      output: {
        assetFileNames: 'media/[name].[hash][extname]'
      }
    }
  }
}

Здесь:

  • assetsDir задаёт верхний уровень
  • assetFileNames управляет внутренней структурой и именами

Итог:

dist/
  assets/
    media/
      logo.8d7f3a.png

При конфликте логики приоритет фактически смещается в сторону Rollup-конфигурации для именования, но assetsDir сохраняет свою роль как корневой контейнер.

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

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

dist/
  assets/
    page1.1a2b.js
    page2.3c4d.js
    common.9f8e.css
    image.7a6b.png

Это позволяет унифицировать размещение ресурсов независимо от количества entry points.

Использование в CDN-сценариях

При использовании CDN assetsDir часто становится частью публичного URL:

export default {
  base: 'https://cdn.example.com/app/',
  build: {
    assetsDir: 'v1/assets'
  }
}

Результат:

https://cdn.example.com/app/v1/assets/logo.abc123.png

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

Частые ошибки при настройке

Одной из типичных ошибок является ожидание, что assetsDir изменит структуру исходного кода или пути import. Это не так: он влияет только на результат сборки.

Также часто путают:

  • изменение publicDir в попытке перенести ассеты
  • изменение root проекта вместо build.assetsDir
  • ожидание, что assetsDir влияет на dev-сервер

В режиме разработки Vite не использует dist и assetsDir не применяется к физическим файлам.

Поведение в dev-режиме

Во время разработки:

  • ассеты отдаются через виртуальный сервер Vite
  • физическая структура dist не создаётся
  • assetsDir игнорируется

Это означает, что влияние параметра проявляется исключительно в production-сборке:

vite build

а не в:

vite

Итоговая роль assetsDir в архитектуре сборки

build.assetsDir выступает как структурный параметр, определяющий организацию итогового output-каталога. Он не влияет на логику модулей, не участвует в трансформации кода и не меняет поведение импорта, но задаёт предсказуемую и управляемую схему размещения всех статических ресурсов внутри production-бандла.

Оглавление