Image (Legacy)

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

Смотрите новый API Reference для 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 или конфигурации загрузчика.

При использовании стандартного загрузчика также учитывайте следующее для исходных изображений:

• Когда src является внешним URL, вы также должны настроить remotePatterns
• Когда src является анимированным или неизвестного формата (JPEG, PNG, WebP, AVIF, GIF, TIFF), изображение будет отдано как есть
• Когда src имеет формат SVG, он будет заблокирован, если не включены unoptimized или dangerouslyAllowSVG

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. Подробности о более редких свойствах можно найти в разделе Advanced Props.

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

Поведение загрузки изображения. По умолчанию 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, исходное изображение будет передаваться как есть из src без изменения качества, размера или формата. По умолчанию false.

Это полезно для изображений, которые не выигрывают от оптимизации, например, маленьких изображений (менее 1 КБ), векторных изображений (SVG) или анимированных изображений (GIF).

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".

Параметры конфигурации

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

Для защиты вашего приложения от злоумышленников требуется настройка для использования внешних изображений. Это гарантирует, что только внешние изображения из вашего аккаунта могут обрабатываться 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.

Домены (Domains)

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

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

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

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

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

Конфигурация загрузчика (Loader Configuration)

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

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

Встроенные загрузчики (Built-in Loaders)

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

• По умолчанию: Работает автоматически с 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.js в будущих обновлениях.

Размеры устройств (Device Sizes)

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

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

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

Размеры изображений (Image Sizes)

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

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

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

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

Допустимые форматы (Acceptable Formats)

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

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

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

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

Вы можете включить поддержку AVIF, которая вернётся к исходному формату изображения src, если браузер не поддерживает AVIF:

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

Полезно знать:

• Мы по-прежнему рекомендуем использовать WebP для большинства случаев.
• AVIF обычно занимает на 50% больше времени для кодирования, но сжимается на 20% лучше по сравнению с WebP. Это означает, что при первом запросе изображения оно обычно будет медленнее, а последующие запросы, которые кэшируются, будут быстрее.
• Если вы размещаете Next.js самостоятельно с Proxy/CDN перед ним, вы должны настроить Proxy для пересылки заголовка Accept.

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

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

Изображения оптимизируются динамически при запросе и сохраняются в каталоге <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, чтобы уменьшить общее количество возможных сгенерированных изображений.
• Вы можете настроить форматы, чтобы отключить несколько форматов в пользу одного формата изображения.

Минимальное время жизни кэша (Minimum Cache TTL)

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

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

module.exports = {
  images: {
    minimumCacheTTL: 60, // 1 минута
  },
}

Вы можете увеличить TTL, чтобы уменьшить количество ревалидаций и потенциально снизить затраты:

module.exports = {
  images: {
    minimumCacheTTL: 2678400, // 31 день
  },
}

Срок истечения (или, точнее, Max Age) оптимизированного изображения определяется либо 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 (Dangerously Allow 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, чтобы предотвратить выполнение скриптов, встроенных в изображение.

contentDispositionType

Загрузчик по умолчанию устанавливает заголовок Content-Disposition в значение attachment для дополнительной защиты, так как API может обслуживать произвольные удалённые изображения.

Значение по умолчанию — attachment, которое заставляет браузер загружать изображение при прямом посещении. Это особенно важно, когда dangerouslyAllowSVG имеет значение true.

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

module.exports = {
  images: {
    contentDispositionType: 'inline',
  },
}

Анимированные изображения (Animated Images)

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

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

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