19. @nuxt/image

🖼️ Модуль @nuxt/image

@nuxt/image — официальный модуль Nuxt для оптимизации изображений. Он автоматически сжимает, конвертирует в WebP и адаптирует размеры изображений под разные экраны.

---

🚀 Установка

npx nuxi module add image

nuxt.config.ts

export default defineNuxtConfig({
  modules: ['@nuxt/image'],
  image: {
    // Качество по умолчанию
    quality: 80,
    // Форматы для конвертации
    format: ['webp', 'avif'],
    // Брейкпоинты экранов
    screens: {
      xs: 320,
      sm: 640,
      md: 768,
      lg: 1024,
      xl: 1280,
      xxl: 1536,
      '2xl': 1536
    }
  }
})

---

🔧 Компонент NuxtImg

<NuxtImg> — замена стандартного <img> с автоматической оптимизацией:

<!-- Базовое использование -->
<NuxtImg src="/images/hero.jpg" alt="Герой" />

<!-- С явными размерами -->
<NuxtImg
  src="/images/hero.jpg"
  alt="Главный баннер"
  width="1200"
  height="600"
/>

<!-- С форматом и качеством -->
<NuxtImg
  src="/images/product.jpg"
  format="webp"
  quality="90"
  alt="Продукт"
/>

<!-- Адаптивное с sizes -->
<NuxtImg
  src="/images/banner.jpg"
  sizes="sm:100vw md:50vw lg:800px"
  alt="Баннер"
/>

<!-- Ленивая загрузка -->
<NuxtImg
  src="/images/card.jpg"
  loading="lazy"
  alt="Карточка"
/>

<!-- Blur-placeholder во время загрузки -->
<NuxtImg
  src="/images/photo.jpg"
  placeholder
  alt="Фото"
/>

<!-- Кастомный placeholder -->
<NuxtImg
  src="/images/photo.jpg"
  :placeholder="[20, 10, 75, 5]"
  alt="Фото с размытым превью"
/>

---

🖼️ Компонент NuxtPicture

<NuxtPicture> генерирует <picture> с несколькими источниками для максимальной совместимости:

<NuxtPicture
  src="/images/hero.jpg"
  alt="Герой страницы"
  :imgAttrs="{ class: 'hero-image' }"
  sizes="xs:100vw sm:100vw md:100vw lg:1920px"
/>

<!-- Генерирует -->
<!--
<picture>
  <source
    type="image/avif"
    srcset="/_ipx/f_avif&s_1920x... 1920w, ..."
  />
  <source
    type="image/webp"
    srcset="/_ipx/f_webp&s_1920x... 1920w, ..."
  />
  <img
    src="/_ipx/f_jpg&s_1920x... "
    alt="Герой страницы"
    class="hero-image"
  />
</picture>
-->

---

☁️ Провайдеры изображений

IPX (локальный, встроенный)

Используется по умолчанию — обрабатывает изображения на сервере:

image: {
  ipx: {
    maxAge: 60 * 60 * 24 * 365 // 1 год кеширования
  }
}

Cloudinary

image: {
  cloudinary: {
    baseURL: 'https://res.cloudinary.com/my-cloud/image/upload/'
  }
}

<NuxtImg
  provider="cloudinary"
  src="/my-image.jpg"
  width="800"
  height="600"
  quality="85"
/>

Imgix

image: {
  imgix: {
    baseURL: 'https://my-project.imgix.net'
  }
}

Vercel

image: {
  vercel: {
    baseURL: 'https://my-project.vercel.app'
  }
}

Unsplash

image: {
  unsplash: {
    baseURL: 'https://images.unsplash.com'
  }
}

---

📐 Параметр sizes

sizes — ключевой параметр для адаптивных изображений:

<!-- Синтаксис: breakpoint:width -->
<NuxtImg
  src="/hero.jpg"
  sizes="xs:100vw sm:100vw md:50vw lg:400px"
  alt="Адаптивное изображение"
/>

<!--
  На xs/sm экранах: 100% ширины viewport
  На md экранах: 50% ширины viewport
  На lg и выше: 400px
-->

<!-- Реальный пример: сетка из 3 колонок -->
<div class="grid grid-cols-1 md:grid-cols-3">
  <NuxtImg
    v-for="item in items"
    :key="item.id"
    :src="item.image"
    sizes="sm:100vw md:33vw"
    loading="lazy"
    class="w-full"
    :alt="item.title"
  />
</div>

---

🌫️ Blur Placeholder

Blur placeholder показывает размытое превью во время загрузки:

<!-- Автоматический blur placeholder -->
<NuxtImg
  src="/images/large-photo.jpg"
  :placeholder="true"
  alt="Фото с blur-эффектом"
/>

<!-- Кастомный: [ширина, высота, качество, blur] -->
<NuxtImg
  src="/images/large-photo.jpg"
  :placeholder="[30, 20, 50, 10]"
  alt="Фото"
/>

<!-- Кастомный цвет -->
<NuxtImg
  src="/images/product.jpg"
  placeholder="#1a1a2e"
  alt="Продукт"
/>

---

⚡ Lazy Loading и Preloading

<!-- Ленивая загрузка (по умолчанию для изображений ниже fold) -->
<NuxtImg
  src="/below-fold-image.jpg"
  loading="lazy"
  alt="Изображение ниже первого экрана"
/>

<!-- Немедленная загрузка (выше fold) -->
<NuxtImg
  src="/above-fold-image.jpg"
  loading="eager"
  preload
  alt="Hero изображение"
/>

// nuxt.config.ts — Preloading для критических изображений
export default defineNuxtConfig({
  image: {
    presets: {
      avatar: {
        modifiers: {
          format: 'webp',
          width: 48,
          height: 48,
          fit: 'cover'
        }
      },
      thumbnail: {
        modifiers: {
          format: 'webp',
          width: 300,
          height: 200,
          fit: 'cover',
          quality: 70
        }
      }
    }
  }
})

<!-- Использование пресета -->
<NuxtImg
  src="/user-avatar.jpg"
  preset="avatar"
  alt="Аватар"
/>

---

🎨 Trансформации изображений

<!-- Обрезка -->
<NuxtImg src="/img.jpg" width="300" height="300" fit="cover" />
<NuxtImg src="/img.jpg" width="300" height="300" fit="contain" />
<NuxtImg src="/img.jpg" width="300" height="300" fit="fill" />

<!-- Позиция обрезки -->
<NuxtImg src="/img.jpg" :modifiers="{ position: 'top-left' }" />

<!-- Фильтры (через провайдер) -->
<NuxtImg
  src="/img.jpg"
  provider="cloudinary"
  :modifiers="{ effect: 'grayscale' }"
/>

---

🔧 useImage composable

Для программного использования трансформаций:

const img = useImage()

// Генерация URL оптимизированного изображения
const optimizedUrl = img('/images/photo.jpg', {
  width: 800,
  height: 600,
  format: 'webp',
  quality: 85
})

// Использование в CSS
const style = {
  backgroundImage: `url(${img('/images/bg.jpg', { width: 1920 })})`
}

---

📊 Сравнение провайдеров

Провайдер	Хостинг	Цена	Особенности
IPX	Self-hosted	Бесплатно	Полный контроль
Cloudinary	Cloud	Freemium	AI-трансформации
Imgix	Cloud	От $25/мес	Мощные трансформации
Vercel	Cloud	Включено	Автоматически
Bunny	CDN	От $0.01/GB	Быстрый CDN

---