Выбор способа

Image Kit умеет готовить изображения несколькими способами, и большинство задач можно решить не одним из них. На этой странице перечислено, что делает каждый способ, чтобы вы выбрали подходящий и перешли к готовой конфигурации.

Две разные задачи легко перепутать:

• Адаптивные варианты — изменение размера исходного изображения до нескольких ширин и форматов (400w, 800w, WebP, AVIF …), чтобы браузер скачивал самый маленький подходящий файл.
• Плейсхолдеры — крошечный HazeHash, BlurHash, ThumbHash или доминирующий цвет вместе с размером изображения, которые показываются, пока грузится настоящее. Ничего не уменьшается и никакие файлы не пишутся.

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

Что вам нужно?

• Размытие на время загрузки для нескольких импортируемых изображений — импорт только плейсхолдера.
• Размытие для многих изображений из папки, которые выбираются по имени файла — import.meta.glob.
• Размытие для изображений, путь которых приходит из данных (:src="item.image", CMS, JSON-файл) — манифест плейсхолдеров из папок. В Nuxt это одна опция.
• Заранее собранные варианты WebP/AVIF нужных размеров — пакетная генерация плагина Vite или команда generate.
• Варианты, которые делаются по запросу, без шага сборки — сервер on-demand или маршрут Nuxt.
• Плейсхолдеры для готового проекта, не трогая его сборку — команда placeholders.
• Изображения на CDN или другом хосте — urls или --url.
• Узнать, как используются изображения, ничего не меняя — команда scan.

Способы рядом

Способ	Пишет файлы	Когда работает	Работает с src, собранным в рантайме	Что нужно
?placeholder (список полей), ?hazehash, ?blurhash, ?color, ?size, ?preview	нет	сборка / dev	нет — один импорт на изображение	плагин Vite, sharp
import.meta.glob с ?placeholder	нет	сборка / dev	по имени файла	плагин Vite, sharp
Манифест из dirs / urls	нет	сборка / dev	да	плагин Vite или Nuxt, sharp
Команда placeholders	манифест или ваши шаблоны	когда вы её запускаете	с --dir / --url	sharp
Импорт ?vik	да	сборка / dev	нет	плагин Vite, sharp
Пакетная генерация (generate)	да	сборка / dev	да — файлы лежат на диске	плагин Vite или CLI, sharp
Сервер on-demand	только кеш	при каждом запросе	да	сервер Node, sharp

thumbhash нужен везде, где считается ThumbHash. См. Установка.

Как плейсхолдер попадает в <VImage>

Любой способ заканчивается одним из трёх путей, и полезно понимать, каким именно вы пользуетесь:

• Пропсы — значения передаются компоненту напрямую: v-bind="placeholder", :hazehash="hash" или записываются в шаблон командой.
• Манифест — карта src → плейсхолдер регистрируется один раз, а <VImage> находит свою запись по точной строке src. Никаких пропсов на каждом использовании. См. Манифест плейсхолдеров.
• Метаданные вариантов — импорт ?vik или сгенерированный манифест несёт плейсхолдер вместе с адресами уменьшенных файлов и передаётся как проп image.

Изображение, импортированное в компонент (import hero from './hero.jpg'), при сборке приложения получает хешированный URL, поэтому поиск в манифесте по src его не найдёт. Для таких изображений используйте пропсы или раздавайте их из папки с постоянным URL.

Рецепты

• Vite и Vue — все конфигурации плагина: от простого размытия до вариантов и манифеста папок вместе.
• Nuxt — опции модуля и случаи, когда плагин Vite нужно добавлять вручную.
• CLI, CDN и удалённые изображения — проекты без плагина, CDN-изображения, проверка в CI.