Компонент <Image> (устаревшая версия)

Начиная с Next.js 13, компонент next/image был переработан для улучшения производительности и удобства разработчиков. Чтобы обеспечить обратную совместимость при обновлении, старый next/image был переименован в next/legacy/image.

Смотрите новую справочную документацию по next/image

Сравнение

По сравнению с next/legacy/image, новый компонент next/image имеет следующие изменения:

• Удалена обёртка <span> вокруг <img> в пользу нативного вычисления соотношения сторон
• Добавлена поддержка стандартного пропа style
  • Удалён проп layout в пользу style или className
  • Удалён проп objectFit в пользу style или className
  • Удалён проп objectPosition в пользу style или className
• Удалена реализация IntersectionObserver в пользу нативной ленивой загрузки
  • Удалён проп lazyBoundary, так как нет нативного аналога
  • Удалён проп lazyRoot, так как нет нативного аналога
• Удалена конфигурация loader в пользу пропа loader
• Проп alt изменён с необязательного на обязательный
• Изменён колбэк onLoadingComplete для получения ссылки на элемент <img>

Обязательные пропсы

Компонент <Image /> требует следующие свойства.

src

Должен быть одним из следующих:

• Статически импортированный файл изображения
• Строка пути. Может быть абсолютным внешним URL или внутренним путём в зависимости от пропа loader или конфигурации загрузчика.

При использовании внешнего URL его необходимо добавить в remotePatterns в next.config.js.

width

Свойство width может представлять либо отображаемую ширину, либо оригинальную ширину в пикселях, в зависимости от свойств layout и sizes.

При использовании layout="intrinsic" или layout="fixed" свойство width представляет отображаемую ширину в пикселях, поэтому будет влиять на размер изображения.

При использовании layout="responsive" или layout="fill" свойство width представляет оригинальную ширину в пикселях, поэтому будет влиять только на соотношение сторон.

Свойство width обязательно, за исключением статически импортированных изображений или изображений с layout="fill".

height

Свойство height может представлять либо отображаемую высоту, либо оригинальную высоту в пикселях, в зависимости от свойств layout и sizes.

При использовании layout="intrinsic" или layout="fixed" свойство height представляет отображаемую высоту в пикселях, поэтому будет влиять на размер изображения.

При использовании layout="responsive" или layout="fill" свойство height представляет оригинальную высоту в пикселях, поэтому будет влиять только на соотношение сторон.

Свойство height обязательно, за исключением статически импортированных изображений или изображений с layout="fill".

Необязательные пропсы

Компонент <Image /> принимает ряд дополнительных свойств помимо обязательных. В этом разделе описаны наиболее часто используемые свойства компонента Image. Подробности о редко используемых свойствах можно найти в разделе Расширенные пропсы.

layout

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

• Демонстрация макета intrinsic (по умолчанию)
  • При intrinsic изображение будет уменьшаться для маленьких областей просмотра, но сохранять оригинальные размеры для больших.
• Демонстрация макета fixed
  • При fixed размеры изображения не изменяются при изменении области просмотра (без адаптивности), аналогично нативному элементу img.
• Демонстрация макета responsive
  • При responsive изображение будет уменьшаться для маленьких областей просмотра и увеличиваться для больших.
  • Убедитесь, что родительский элемент использует display: block в своих стилях.
• Демонстрация макета fill
  • При fill изображение растягивается по ширине и высоте до размеров родительского элемента, при условии, что родительский элемент имеет относительное позиционирование.
  • Обычно используется вместе со свойством objectFit.
  • Убедитесь, что родительский элемент имеет position: relative в своих стилях.
• Демонстрация фонового изображения

loader

Пользовательская функция для разрешения URL. Установка загрузчика как пропа компонента Image переопределяет загрузчик по умолчанию, определённый в разделе images файла next.config.js.

loader — это функция, возвращающая строку URL для изображения с учётом следующих параметров:

• src
• width
• quality

Пример использования пользовательского загрузчика:

import Image from 'next/legacy/image'

const myLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

const MyImage = (props) => {
  return (
    <Image
      loader={myLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

sizes

Строка, предоставляющая информацию о ширине изображения на разных контрольных точках. Значение sizes значительно влияет на производительность для изображений с layout="responsive" или layout="fill". Игнорируется для изображений с layout="intrinsic" или layout="fixed".

Свойство sizes выполняет две важные функции, связанные с производительностью изображений:

Во-первых, значение sizes используется браузером для определения, какой размер изображения загружать из автоматически сгенерированного набора источников next/legacy/image. Когда браузер делает выбор, он ещё не знает размер изображения на странице, поэтому выбирает изображение того же размера или больше, чем область просмотра. Свойство sizes позволяет сообщить браузеру, что изображение на самом деле будет меньше, чем полный экран. Если вы не укажете значение sizes, будет использоваться значение по умолчанию 100vw (ширина полного экрана).

Во-вторых, значение sizes анализируется и используется для обрезки значений в автоматически созданном наборе источников. Если свойство sizes включает значения типа 50vw, которые представляют процент от ширины области просмотра, то набор источников обрезается, чтобы исключить значения, которые слишком малы для использования.

Например, если вы знаете, что ваши стили приведут к тому, что изображение будет занимать всю ширину на мобильных устройствах, располагаться в 2 колонки на планшетах и в 3 колонки на десктопах, вы должны указать свойство sizes примерно так:

import Image from 'next/legacy/image'
const Example = () => (
  <div className="grid-element">
    <Image
      src="/example.png"
      layout="fill"
      sizes="(max-width: 768px) 100vw,
              (max-width: 1200px) 50vw,
              33vw"
    />
  </div>
)

Этот пример sizes может значительно повлиять на показатели производительности. Без 33vw выбранное с сервера изображение было бы в 3 раза шире, чем необходимо. Поскольку размер файла пропорционален квадрату ширины, без sizes пользователь загружал бы изображение в 9 раз больше необходимого.

Узнайте больше о srcset и sizes:

• web.dev
• mdn

quality

Качество оптимизированного изображения, целое число от 1 до 100, где 100 — наилучшее качество. По умолчанию 75.

priority

Если true, изображение будет считаться высокоприоритетным и предзагружаться. Ленивая загрузка автоматически отключается для изображений с priority.

Свойство priority следует использовать для любого изображения, определённого как Largest Contentful Paint (LCP). Может быть уместным иметь несколько приоритетных изображений, так как разные изображения могут быть LCP-элементами для разных размеров области просмотра.

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

placeholder

Заполнитель, используемый во время загрузки изображения. Возможные значения: blur или empty. По умолчанию empty.

При blur в качестве заполнителя будет использоваться свойство blurDataURL. Если src — это объект из статического импорта и импортированное изображение имеет формат .jpg, .png, .webp или .avif, то blurDataURL будет заполнено автоматически.

Для динамических изображений вы должны предоставить свойство blurDataURL. Решения вроде Plaiceholder могут помочь с генерацией base64.

При empty во время загрузки изображения не будет заполнителя, только пустое пространство.

Попробуйте:

• Демонстрация заполнителя blur
• Демонстрация эффекта мерцания с пропом blurDataURL
• Демонстрация цветного эффекта с пропом blurDataURL

Расширенные пропсы

В некоторых случаях может потребоваться более продвинутое использование. Компонент <Image /> опционально принимает следующие расширенные свойства.

style

Позволяет передавать CSS-стили для базового элемента изображения.

Обратите внимание, что все режимы layout применяют свои собственные стили к элементу изображения, и эти автоматические стили имеют приоритет над пропом style.

Также учитывайте, что обязательные пропсы width и height могут взаимодействовать с вашими стилями. Если вы используете стили для изменения width изображения, вы должны также установить стиль height="auto", иначе изображение будет искажено.

objectFit

Определяет, как изображение будет заполнять родительский контейнер при layout="fill".

Это значение передаётся в CSS-свойство object-fit для изображения src.

objectPosition

Определяет позиционирование изображения внутри родительского элемента при layout="fill".

Это значение передаётся в CSS-свойство object-position, применяемое к изображению.

onLoadingComplete

Колбэк-функция, вызываемая после полной загрузки изображения и удаления заполнителя.

Функция onLoadingComplete принимает один параметр — объект со следующими свойствами:

• naturalWidth
• naturalHeight

loading

Внимание: Это свойство предназначено только для продвинутого использования. Переключение изображения на загрузку с eager обычно ухудшает производительность.

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

Поведение загрузки изображения. По умолчанию lazy.

При lazy откладывает загрузку изображения до достижения расчётного расстояния от области просмотра.

При eager загружает изображение немедленно.

Узнайте больше

blurDataURL

Data URL, используемый в качестве заполнителя до успешной загрузки изображения src. Работает только в сочетании с placeholder="blur".

Должен быть изображением в кодировке base64. Оно будет увеличено и размыто, поэтому рекомендуется использовать очень маленькое изображение (10px или меньше). Использование больших изображений в качестве заполнителей может ухудшить производительность вашего приложения.

Попробуйте:

• Демонстрация пропа blurDataURL по умолчанию
• Демонстрация эффекта мерцания с пропом blurDataURL
• Демонстрация цветного эффекта с пропом blurDataURL

Вы также можете сгенерировать Data URL однотонного цвета, чтобы он соответствовал изображению.

lazyBoundary

Строка (с синтаксисом, аналогичным свойству margin), которая действует как ограничивающая рамка для обнаружения пересечения изображения с областью просмотра и запуска ленивой загрузки. По умолчанию "200px".

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

Узнайте больше

lazyRoot

React Ref, указывающий на прокручиваемый родительский элемент. По умолчанию null (область просмотра документа).

Ref должен указывать на DOM-элемент или React-компонент, который передаёт Ref базовому DOM-элементу.

Пример указания на DOM-элемент

import Image from 'next/legacy/image'
import React from 'react'

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <div ref={lazyRoot} style={{ overflowX: 'scroll', width: '500px' }}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </div>
  )
}

Пример указания на React-компонент

import Image from 'next/legacy/image'
import React from 'react'

const Container = React.forwardRef((props, ref) => {
  return (
    <div ref={ref} style={{ overflowX: 'scroll', width: '500px' }}>
      {props.children}
    </div>
  )
})

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <Container ref={lazyRoot}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </Container>
  )
}

Узнайте больше

unoptimized

Если установлено в true, исходное изображение будет отображаться как есть, без изменения качества, размера или формата. По умолчанию false.

import Image from 'next/image'

const UnoptimizedImage = (props) => {
  return <Image {...props} unoptimized />
}

Начиная с Next.js 12.3.0, это свойство можно применить ко всем изображениям, обновив next.config.js следующей конфигурацией:

module.exports = {
  images: {
    unoptimized: true,
  },
}

Другие свойства

Остальные свойства компонента <Image /> будут переданы базовому элементу img, за исключением следующих:

• srcSet. Вместо этого используйте Размеры устройств.
• ref. Вместо этого используйте onLoadingComplete.
• decoding. Всегда имеет значение "async".

Настройки конфигурации

Шаблоны удалённых изображений

Для защиты вашего приложения от злоумышленников требуется настройка для использования внешних изображений. Это гарантирует, что только изображения из вашего аккаунта будут обрабатываться API оптимизации изображений Next.js. Эти внешние изображения можно настроить с помощью свойства remotePatterns в файле next.config.js, как показано ниже:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
        port: '',
        pathname: '/account123/**',
        search: '',
      },
    ],
  },
}

Полезно знать: В примере выше свойство src компонента next/legacy/image должно начинаться с https://example.com/account123/ и не должно содержать строки запроса. Любой другой протокол, имя хоста, порт или несоответствующий путь вернут ответ 400 Bad Request.

Ниже приведён пример свойства remotePatterns в файле next.config.js с использованием шаблона с подстановочными знаками в hostname:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
        port: '',
        search: '',
      },
    ],
  },
}

Полезно знать: В примере выше свойство src компонента next/legacy/image должно начинаться с https://img1.example.com, https://me.avatar.example.com или любого количества поддоменов. Оно не может содержать порт или строку запроса. Любой другой протокол или несоответствующее имя хоста вернут ответ 400 Bad Request.

Шаблоны с подстановочными знаками можно использовать как для pathname, так и для hostname, и они имеют следующий синтаксис:

• * соответствует одному сегменту пути или поддомену
• ** соответствует любому количеству сегментов пути в конце или поддоменов в начале

Синтаксис ** не работает в середине шаблона.

Полезно знать: Если опустить protocol, port, pathname или search, то подразумевается подстановочный знак **. Это не рекомендуется, так как может позволить злоумышленникам оптимизировать URL-адреса, которые вы не планировали.

Ниже приведён пример свойства remotePatterns в файле next.config.js с использованием search:

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.example.com',
        search: '?v=1727111025337',
      },
    ],
  },
}

Полезно знать: В примере выше свойство src компонента next/legacy/image должно начинаться с https://assets.example.com и содержать точную строку запроса ?v=1727111025337. Любой другой протокол или строка запроса вернут ответ 400 Bad Request.

Домены

Предупреждение: Устарело в Next.js 14 в пользу строгих remotePatterns для защиты вашего приложения от злоумышленников. Используйте domains только если вы владеете всем контентом, обслуживаемым с домена.

Аналогично remotePatterns, конфигурация domains может использоваться для предоставления списка разрешённых имён хостов для внешних изображений.

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

Ниже приведён пример свойства domains в файле next.config.js:

module.exports = {
  images: {
    domains: ['assets.acme.com'],
  },
}

Настройка загрузчика

Если вы хотите использовать облачного провайдера для оптимизации изображений вместо встроенного API оптимизации изображений Next.js, вы можете настроить loader и префикс path в файле next.config.js. Это позволяет использовать относительные URL-адреса для свойства src изображения и автоматически генерировать правильный абсолютный URL для вашего провайдера.

module.exports = {
  images: {
    loader: 'imgix',
    path: 'https://example.com/myaccount/',
  },
}

Встроенные загрузчики

Следующие облачные провайдеры оптимизации изображений включены:

• По умолчанию: Работает автоматически с next dev, next start или пользовательским сервером
• Vercel: Работает автоматически при развёртывании на Vercel, не требует настройки. Подробнее
• Imgix: loader: 'imgix'
• Cloudinary: loader: 'cloudinary'
• Akamai: loader: 'akamai'
• Пользовательский: loader: 'custom' использует пользовательского облачного провайдера, реализуя свойство loader компонента next/legacy/image

Если вам нужен другой провайдер, вы можете использовать свойство loader с next/legacy/image.

Изображения не могут быть оптимизированы во время сборки с использованием output: 'export', только по запросу. Чтобы использовать next/legacy/image с output: 'export', вам нужно использовать загрузчик, отличный от стандартного. Подробнее в обсуждении.

Стандартный загрузчик компонента next/legacy/image использует squoosh, так как он быстро устанавливается и подходит для среды разработки. При использовании next start в производственной среде настоятельно рекомендуется установить sharp, выполнив npm i sharp в директории проекта. Это не требуется для развёртываний на Vercel, так как sharp устанавливается автоматически.

Продвинутые настройки

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

Размеры устройств

Если вы знаете ожидаемые ширины устройств ваших пользователей, вы можете указать список точек останова ширины устройств с помощью свойства deviceSizes в next.config.js. Эти ширины используются, когда компонент next/legacy/image использует layout="responsive" или layout="fill", чтобы гарантировать, что правильное изображение будет обслуживаться для устройства пользователя.

Если конфигурация не предоставлена, используется стандартная, указанная ниже.

module.exports = {
  images: {
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
  },
}

Размеры изображений

Вы можете указать список ширин изображений с помощью свойства images.imageSizes в файле next.config.js. Эти ширины объединяются с массивом размеров устройств, чтобы сформировать полный массив размеров, используемых для генерации srcset изображений.

Причина разделения на два списка в том, что imageSizes используется только для изображений, которые предоставляют свойство sizes, указывающее, что изображение меньше полной ширины экрана. Поэтому размеры в imageSizes должны быть меньше, чем наименьший размер в deviceSizes.

Если конфигурация не предоставлена, используется стандартная, указанная ниже.

module.exports = {
  images: {
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
  },
}

Поддерживаемые форматы

Стандартный API оптимизации изображений автоматически определяет поддерживаемые браузером форматы изображений через заголовок Accept запроса.

Если заголовок Accept соответствует более чем одному из настроенных форматов, используется первое совпадение в массиве. Поэтому порядок массива имеет значение. Если совпадений нет (или исходное изображение анимировано), API оптимизации изображений вернётся к исходному формату изображения.

Если конфигурация не предоставлена, используется стандартная, указанная ниже.

module.exports = {
  images: {
    formats: ['image/webp'],
  },
}

Вы можете включить поддержку AVIF следующей конфигурацией.

module.exports = {
  images: {
    formats: ['image/avif', 'image/webp'],
  },
}

Полезно знать: AVIF обычно занимает на 20% больше времени для кодирования, но сжимается на 20% лучше по сравнению с WebP. Это означает, что при первом запросе изображения оно обычно будет медленнее, а последующие запросы, которые кэшируются, будут быстрее.

Поведение кэширования

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

Изображения оптимизируются динамически при запросе и сохраняются в директории <distDir>/cache/images. Оптимизированный файл изображения будет обслуживаться для последующих запросов до истечения срока действия. Когда поступает запрос, соответствующий кэшированному, но устаревшему файлу, устаревшее изображение сразу же возвращается. Затем изображение оптимизируется в фоновом режиме (так называемая ревалидация) и сохраняется в кэше с новым сроком действия.

Статус кэша изображения можно определить, прочитав значение заголовка ответа x-nextjs-cache (x-vercel-cache при развёртывании на Vercel). Возможные значения следующие:

• MISS - путь отсутствует в кэше (происходит максимум один раз, при первом посещении)
• STALE - путь есть в кэше, но превышено время ревалидации, поэтому он будет обновлён в фоновом режиме
• HIT - путь есть в кэше и не превышено время ревалидации

Срок действия (или, точнее, Max Age) определяется либо конфигурацией minimumCacheTTL, либо заголовком Cache-Control исходного изображения, в зависимости от того, что больше. Конкретно используется значение max-age заголовка Cache-Control. Если найдены и s-maxage, и max-age, предпочтение отдаётся s-maxage. Значение max-age также передаётся всем нижестоящим клиентам, включая CDN и браузеры.

• Вы можете настроить minimumCacheTTL, чтобы увеличить время кэширования, когда исходное изображение не включает заголовок Cache-Control или его значение очень мало.
• Вы можете настроить deviceSizes и imageSizes, чтобы уменьшить общее количество возможных сгенерированных изображений.
• Вы можете настроить форматы, чтобы отключить несколько форматов в пользу одного.

Минимальное время жизни кэша

Вы можете настроить Time to Live (TTL) в секундах для кэшированных оптимизированных изображений. Во многих случаях лучше использовать Статический импорт изображений, который автоматически хеширует содержимое файла и кэширует изображение навсегда с заголовком Cache-Control со значением immutable.

module.exports = {
  images: {
    minimumCacheTTL: 60,
  },
}

Срок действия оптимизированного изображения определяется либо minimumCacheTTL, либо заголовком Cache-Control исходного изображения, в зависимости от того, что больше.

Если вам нужно изменить поведение кэширования для конкретного изображения, вы можете настроить headers, чтобы установить заголовок Cache-Control для исходного изображения (например, /some-asset.jpg, а не для /_next/image).

На данный момент нет механизма для инвалидации кэша, поэтому лучше держать minimumCacheTTL небольшим. В противном случае вам может потребоваться вручную изменить свойство src или удалить <distDir>/cache/images.

Отключение статического импорта

Стандартное поведение позволяет импортировать статические файлы, такие как import icon from './icon.png', а затем передавать их в свойство src.

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

Вы можете отключить статический импорт изображений в next.config.js:

module.exports = {
  images: {
    disableStaticImages: true,
  },
}

Опасное разрешение SVG

Стандартный загрузчик не оптимизирует SVG-изображения по нескольким причинам. Во-первых, SVG — это векторный формат, что означает, что его можно масштабировать без потерь. Во-вторых, SVG имеет много функций, аналогичных HTML/CSS, что может привести к уязвимостям без правильных заголовков Content Security Policy (CSP).

Поэтому мы рекомендуем использовать свойство unoptimized, когда известно, что свойство src содержит SVG. Это происходит автоматически, когда src заканчивается на ".svg".

Однако, если вам нужно обслуживать SVG-изображения с помощью стандартного API оптимизации изображений, вы можете установить dangerouslyAllowSVG в next.config.js:

module.exports = {
  images: {
    dangerouslyAllowSVG: true,
    contentDispositionType: 'attachment',
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
}

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

Анимированные изображения

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

Автоопределение анимированных файлов работает по возможности и поддерживает GIF, APNG и WebP. Если вы хотите явно пропустить оптимизацию для определённого анимированного изображения, используйте свойство unoptimized.

История версий