Директория public и её особенности

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

Главная особенность заключается в том, что содержимое public обслуживается напрямую сервером разработки и переносится в корень билд-вывода без модификаций.

Базовая модель работы public

При запуске проекта через Vite:

• файлы из public доступны по абсолютному пути
• они не импортируются через JavaScript
• они не проходят через Rollup-пайплайн
• они не участвуют в хешировании и оптимизации

Фактически Vite рассматривает public как статический корень, аналогичный директории static в других инструментах.

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

project/
  public/
    favicon.ico
    robots.txt
    images/
      logo.png
  src/
    main.js

Файл public/favicon.ico будет доступен по адресу:

/favicon.ico

Отличие public от assets в src

Ключевое различие между public и ресурсами внутри src заключается в способе обработки.

Файлы в src

• импортируются через JavaScript или CSS
• обрабатываются Vite (минификация, хеширование)
• участвуют в tree-shaking
• могут быть оптимизированы

Пример:

import logo from './assets/logo.png'

Файлы в public

• не импортируются
• не изменяются сборщиком
• используются через абсолютные URL

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

<img src="/images/logo.png" />

Когда использовать public

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

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

Статические ресурсы без обработки

• favicon и иконки браузера
• robots.txt и sitemap.xml
• файлы верификации домена
• статические JSON-ответы

Файлы с фиксированными URL

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

Пример:

/config/runtime.json

Этот файл можно запрашивать напрямую:

fetch('/config/runtime.json')

Большие файлы без необходимости оптимизации

Иногда требуется разместить:

• видео
• архивы
• большие изображения
• шрифты, которые не нужно обрабатывать

Поведение в режиме разработки

Vite dev server обслуживает public как статический каталог на корне сервера.

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

• доступ без префикса /public
• отсутствие кешбастинга
• мгновенная доступность изменений без пересборки

Пример:

public/data/sample.json

Доступ:

http://localhost:5173/data/sample.json

Поведение в production-сборке

При выполнении сборки (vite build) содержимое public:

• копируется в корень выходной директории (dist)
• сохраняет структуру каталогов
• не получает hash в имени файла
• не модифицируется

Пример результата:

dist/
  index.html
  assets/
  images/
    logo.png
  robots.txt

Файл public/robots.txt станет dist/robots.txt.

Ограничения использования public

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

Отсутствие оптимизации

Файлы:

• не минифицируются
• не кешируются через хеши
• не оптимизируются по размеру

Отсутствие импортной системы

Нельзя использовать:

import data from '/data.json'

Такой подход не работает через систему модулей Vite.

Отсутствие контроля зависимостей

Vite не отслеживает:

• используется файл или нет
• где он подключён
• можно ли удалить файл безопасно

Абсолютные пути и особенности резолва

Все файлы из public доступны только через абсолютный путь от корня сайта.

Пример:

public/images/icon.png

Доступ:

/images/icon.png

Использование относительных путей:

<img src="images/icon.png" />

может привести к ошибкам при вложенной маршрутизации.

Влияние base path

При настройке base в vite.config.js поведение public корректируется.

Пример:

export default {
  base: '/app/'
}

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

public/logo.png

будет доступен как:

/app/logo.png

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

Работа с HTML и public

Файлы из public часто используются напрямую в index.html.

Пример:

<link rel="icon" href="/favicon.ico" />

или

<script src="/config/runtime.js"></script>

Важно учитывать, что такие пути должны быть абсолютными.

Использование с динамическими данными

Директория public может содержать JSON или конфигурационные файлы, которые загружаются во время выполнения приложения.

Пример:

async function loadConfig() {
  const res = await fetch('/config/app.json')
  return await res.json()
}

Это позволяет отделять конфигурацию от кода сборки.

Кеширование и контроль версий

Так как файлы в public не получают хеши, контроль кеширования осуществляется через серверные заголовки.

Типичные подходы:

• отключение кеша для конфигураций
• долгосрочный кеш для медиафайлов
• ручное версионирование имени файла

Пример:

logo.v2.png

Безопасность и доступность

Все файлы в public становятся публично доступными через HTTP.

Следствия:

• нельзя размещать секретные данные
• конфигурации должны быть безопасными для клиента
• любые файлы доступны напрямую по URL

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

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

import data from '/data.json'

Ошибка, так как public не является модульной системой.

Использование относительных путей

<img src="images/logo.png" />

Проблема возникает при переходах между роутами.

Дублирование ресурсов

Иногда файл одновременно размещают в src/assets и public, что приводит к:

• увеличению размера сборки
• путанице в источниках данных

Взаимодействие с SPA и маршрутизацией

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

Пример проблемы:

/user/profile

Если используется:

<img src="avatar.png" />

браузер попытается загрузить:

/user/avatar.png

Правильный вариант:

<img src="/avatar.png" />

Рекомендации по архитектуре использования

Рациональное использование public предполагает разделение ответственности:

• src/assets — управляемые ресурсы, проходящие через сборку
• public — статические файлы без обработки
• конфигурации — только если они публичные и неизменяемые

Такой подход снижает риски неконтролируемого роста статических ресурсов и упрощает предсказуемость сборки