next/image

示例

Image Componentopen in new window

注意: 此页面是next/image组件的API参考。有关功能概述和使用信息，请参阅[图像组件和图像优化]（/docs/guide/basic-features/image-optimization）文档。

注意: 如果您使用的是 Next.js 13 之前的版本，您需要使用 next/legacy/image 文档，因为该组件已重命名.

该next/image组件使用浏览器原生延迟加载，对于 Safari 15.4 之前的旧浏览器，它可能会回退到预加载。使用模糊占位符时，Safari 12 之前的旧版浏览器将回退到空占位符。将样式与width/ height一起使用时，可能会在 Safari 15 之前不保留纵横比的auto旧版浏览器上导致布局偏移。有关详细信息，请参阅此 MDN 视频open in new window。

已知的浏览器Bug

Safari 15open in new window在加载时显示灰色边框。可能的解决方案:
使用 CSS@media not all and (min-resolution:.001dpcm) { img[loading="lazy"] { clip-path: inset(0.5px) } }
使用priority如果图像在首屏之上
Firefox 67+open in new window加载时显示白色背景。可能的解决方案：
启用AVIFformats
使用placeholder="blur"

必须的 Props

<Image /> 组件需要以下属性。

src

必须是以下之一：

静态导入图片文件, or
路径字符串. 这可以是绝对外部 URL，也可以是内部路径，具体取决于loader属性。

使用外部 URL 时，必须将其添加到 remotePatternsinnext.config.js。

width

width 属性表示以像素为单位的渲染宽度，因此它会影响图像显示的大小。

必需，但静态导入的图像或具有fill属性的图像除外。

height

height 属性表示以像素为单位的渲染高度，因此它将影响图像显示的大小。

必需，但静态导入的图像或具有fill属性的图像除外。

alt

alt 属性用于为屏幕阅读器和搜索引擎描述图像。如果图像已被禁用或加载图像时发生错误，它也是后备文本。

它应该包含可以替换图像的文本不改变页面的含义open in new window. 它不是为了补充图像，也不应该重复图像上方或下方的标题中已经提供的信息。

如果图像是纯装饰性的open in new window或不是供用户使用open in new window，alt属性应该是一个空字符串(alt="")。

学习更多open in new window

可选的 Props

<Image /> 组件接受许多超出所需属性的附加属性。本节介绍 Image 组件最常用的属性。在 Advanced Props 部分找到更多不常用属性的详细信息。

loader

用于解析图像 URL 的自定义函数。

loader 是一个返回图像 URL 字符串的函数，给定以下参数：

src
width
quality

这是使用自定义loader的示例：

import Image from 'next/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}
    />
  )
}

或者，您可以使用 next.config.js 中的 loaderFile 配置来配置应用程序中的每个next/image 实例，而无需传递道具。

fill

一个布尔值，导致图像填充父元素，而不是设置 width 和 height。

父元素必须指定position: "relative"、position: "fixed" 或position: "absolute" 样式。

默认情况下，img 元素会自动分配position: "absolute"样式。

默认图像适合行为将拉伸图像以适合容器。您可能更喜欢设置object-fit: "contain" 来设置一个经过信箱处理以适应容器并保持纵横比的图像。

或者，object-fit: "cover" 将导致图像填充整个容器并被裁剪以保持纵横比。为了使其看起来正确，应该将overflow: "hidden"样式分配给父元素。

也可以看看:

sizes

一个字符串，提供有关图像在不同断点处的宽度信息。 sizes 的值将极大地影响使用 fill 或样式设置为具有响应大小的图像的性能。

sizes 属性有两个与图像性能相关的重要目的：

首先，浏览器使用 sizes 的值来确定要从 next/image 自动生成的源集中下载的图像大小。浏览器选择时，还不知道页面上图片的尺寸，所以会选择与视口尺寸相同或更大的图片。 sizes 属性允许您告诉浏览器图像实际上将小于全屏。如果您没有在具有fill属性的图像中指定sizes值，则使用默认值100vw（全屏宽度）。

其次，sizes属性配置next/image如何自动生成图像源集。如果不存在 sizes 值，则生成一个小的源集，适用于固定大小的图像。如果定义了sizes，则会生成一个大型源集，适用于响应式图像。如果sizes属性包含诸如50vw之类的大小，它代表视口宽度的百分比，则源集将被修剪为不包含任何太小而不必要的值。

例如，如果您知道您的样式会导致图像在移动设备上是全宽的，在平板电脑上是 2 列布局，在桌面显示器上是 3 列布局，您应该包括如下的 sizes 属性：

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

此示例的sizes可能会对性能指标产生巨大影响。如果没有 33vw 尺寸，从服务器选择的图像将是所需宽度的 3 倍。因为文件大小与宽度的平方成正比，如果没有 sizes，用户会下载比需要大 9 倍的图像。

了解更多关于 srcset 和 sizes 的信息：

web.devopen in new window- mdnopen in new window

quality

优化图像的质量，介于1和100之间的整数，其中100是最佳质量，因此文件大小最大。默认为75。

priority

当为true时，图像将被视为高优先级和预加载open in new window。使用 priority 的图像会自动禁用延迟加载。

您应该在检测为 Largest Contentful Paint (LCP) 元素的任何图像上使用 priority 属性。拥有多个优先级图像可能是合适的，因为不同的图像可能是不同视口大小的 LCP 元素。

仅当图像在首屏可见时才应使用。默认为false。

placeholder

加载图像时使用的占位符。可能的值为blur 或empty。默认为“空”。

当blur时，blurDataURL属性将用作占位符。如果src是来自静态导入的对象并且导入的图像是.jpg、.png、.webp , 或者.avif，然后blurDataURL 将被自动填充。

对于动态图像，您必须提供 blurDataURL 属性。 Plaiceholderopen in new window 等解决方案可以帮助生成 base64。

当empty时，加载图像时不会有占位符，只有空白。

试试看：

Advanced Props

在某些情况下，您可能需要更高级的用法。 <Image /> 组件可选择接受以下高级属性。

style

允许传递 CSS 样式open in new window 到底层图像元素。

还要记住，所需的width和height道具可以与您的样式交互。如果您使用样式修改图像的width，则必须同时设置height="auto"样式，否则您的图像将被扭曲。

onLoadingComplete

一旦图像完全加载并且 placeholder 已被删除，就会调用回调函数。

回调函数将使用一个参数调用，即对底层<img>元素的引用。

onLoad

加载图像时调用的回调函数。

请注意，加载事件可能会在占位符被移除和图像完全解码之前发生。

相反，使用 onLoadingComplete。

onError

图片加载失败时调用的回调函数。

loading

注意：此属性仅供高级使用。切换一个使用eager加载的图像通常会损害性能。我们建议改用priority属性，它为几乎所有用例正确加载图像。

图片的加载行为。默认为lazy。

当 lazy 时，延迟加载图像，直到它到达计算出的距离视口。

当 eager 时，立即加载图像。

学到更多open in new window

blurDataURL

AData URLopen in new windowto be used as a placeholder image before thesrcimage successfully loads. Only takes effect when combined withplaceholder="blur". 在成功加载图像之前用作占位符图像的数据 URLopen in new window 。 src仅在与结合使用时生效placeholder="blur"。

必须是 base64 编码的图像。它会被放大和模糊，所以一个非常小的图像（10px 或少）推荐。包含较大的图像作为占位符可能会损害您的应用程序性能。

试试看：

您还可以生成纯色数据 URLopen in new window 来匹配图像。

unoptimized

如果为真，源图像将按原样提供，而不是改变质量，大小或格式。默认为false。

通过使用以下配置更新next.config.js，可以将此prop分配给所有图像：

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

Other Props

<Image /> 组件上的其他属性将传递给底层的 img 元素，但以下内容除外：

srcSet. 请改用设备大小。
ref. 使用onLoadingComplete代替.
decoding. 它总是"async".

配置选项

远程模式

为了保护您的应用程序免受恶意用户的侵害，需要进行配置才能使用外部图像。这确保 Next.js 图像优化 API 只能提供您帐户中的外部图像。这些外部图像可以在您的 next.config.js 文件中使用 remotePatterns 属性进行配置，如下所示：

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

注意：上面的例子会保证next/image的src属性必须以https://example.com/account123/开头。任何其他协议、主机名、端口或不匹配的路径将以 400 Bad Request 响应。

下面是next.config.js文件中remotePatterns属性的另一个例子：

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

注意：上面的例子会确保next/image的src属性必须以https://img1.example.com或https://me.avatar.example.com或任意数量开头子域。任何其他协议或不匹配的主机名将以 400 Bad Request 响应。

通配符模式可用于“路径名”和“主机名”，并具有以下语法：

*匹配单个路径段或子域
**匹配末尾任意数量的路径段或开头的子域

** 语法在middle模式不起作用

Domains

注意：我们建议改用remotePatterns，以便您可以限制协议和路径名。

与 remotePatterns 类似，domains 配置可用于为外部图像提供允许的主机名列表。

但是，domains 配置不支持通配符模式匹配，也不能限制协议、端口或路径名。

下面是next.config.js文件中domains属性的示例：

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

Loader Configuration

如果你想使用云提供商来优化图像，而不是使用 Next.js 内置的图像优化 API，你可以在你的next.config.js中配置loaderFile，如下所示：

module.exports = {
  images: {
    loader: 'custom',
    loaderFile: './my/image/loader.js',
  },
}

这必须指向一个相对于 Next.js 应用程序根目录的文件。该文件必须导出一个返回字符串的默认函数，例如：

export default function myImageLoader({ src, width, quality }) {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

或者，您可以使用 loaderprop 来配置 next/image 的每个实例。

Advanced

以下配置适用于高级用例，通常不是必需的。如果您选择配置以下属性，您将在未来的更新中覆盖对 Next.js 默认值的任何更改。

Device Sizes

如果您知道用户的预期设备宽度，则可以使用 next.config.js 中的 deviceSizes 属性指定设备宽度断点列表。这些宽度在next/image组件使用sizesprop 时使用，以确保为用户设备提供正确的图像。

如果没有提供配置，则使用下面的默认值。

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

Image Sizes

您可以使用next.config.js文件中的images.imageSizes属性指定图像宽度列表。这些宽度与设备尺寸的数组连接在一起，形成用于生成图像 srcsetopen in new window 的完整尺寸数组 .

有两个单独列表的原因是 imageSizes 仅用于提供 sizesprop 的图像，这表示图像小于屏幕的整个宽度。 因此，imageSizes中的尺寸都应该小于deviceSizes中的最小尺寸。

如果没有提供配置，则使用下面的默认值。

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

Acceptable Formats

默认的图片优化API会通过请求的Accept头自动检测浏览器支持的图片格式。

如果 Accept 头匹配多个配置格式，则使用数组中的第一个匹配项。因此，数组顺序很重要。如果没有匹配项（或者源图像是 animated），图像优化 API 将回退到原始图像的格式。

如果没有提供配置，则使用下面的默认值。

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

您可以使用以下配置启用 AVIF 支持。

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

注意：与 WebP 相比，AVIF 的编码时间通常要长 20%，但压缩量要小 20%。这意味着第一次请求图像时，它通常会比较慢，然后缓存的后续请求会更快。

注意：如果您在 Next.js 前面使用代理/CDN 自托管，则必须配置代理以转发 Accept 标头。

缓存行为

下面介绍默认 loader 的缓存算法。对于所有其他加载程序，请参阅您的云提供商的文档。

图像根据请求动态优化并存储在<distDir>/cache/images目录中。优化后的图像文件将为后续请求提供服务，直到达到到期为止。当请求与缓存但过期的文件匹配时，过期的图像会立即失效。然后图像在后台再次优化（也称为重新验证）并使用新的到期日期保存到缓存中。

图像的缓存状态可以通过读取 x-nextjs-cache 响应头的值来确定。可能的值如下：

MISS- 该路径不在缓存中（最多出现一次，在第一次访问时）
STALE- 该路径在缓存中但超过了重新验证时间，因此它将在后台更新
HIT- 路径在缓存中且未超过重新验证时间

过期（或者更确切地说是 Max Age）由 minimumCacheTTL 配置或上游图像 Cache-Control 标头定义，以较大者为准。具体来说，使用了“Cache-Control”标头的“max-age”值。如果 s-maxage 和 max-age 都找到了，那么 s-maxage 是首选。 max-age 也会传递给任何下游客户端，包括 CDN 和浏览器。

You can configure minimumCacheTTL to increase the cache duration when the upstream image does not include Cache-Control header or the value is very low.
You can configure deviceSizes and imageSizes to reduce the total number of possible generated images.- You can configure [formats] (#acceptable-formats)to disable multiple formats in favor of a single image format.

Minimum Cache TTL

You can configure the Time to Live (TTL) in seconds for cached optimized images. In many cases, it's better to use aStatic Image Importwhich will automatically hash the file contents and cache the image forever with aCache-Controlheader ofimmutable.

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

The expiration (or rather Max Age) of the optimized image is defined by either theminimumCacheTTLor the upstream imageCache-Controlheader, whichever is larger.

If you need to change the caching behavior per image, you can configureheadersto set theCache-Controlheader on the upstream image (e.g./some-asset.jpg, not/_next/imageitself).

There is no mechanism to invalidate the cache at this time, so its best to keepminimumCacheTTLlow. Otherwise you may need to manually change thesrcprop or delete<distDir>/cache/images.

Disable Static Imports

The default behavior allows you to import static files such asimport icon from './icon.pngand then pass that to thesrcproperty.

In some cases, you may wish to disable this feature if it conflicts with other plugins that expect the import to behave differently.

You can disable static image imports inside yournext.config.js:

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

Dangerously Allow SVG

The defaultloaderdoes not optimize SVG images for a few reasons. First, SVG is a vector format meaning it can be resized losslessly. Second, SVG has many of the same features as HTML/CSS, which can lead to vulnerabilities without properContent Security Policy (CSP) headers.

If you need to serve SVG images with the default Image Optimization API, you can setdangerouslyAllowSVGandcontentSecurityPolicyinside yournext.config.js:

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

Animated Images

The defaultloaderwill automatically bypass Image Optimization for animated images and serve the image as-is.

Auto-detection for animated files is best-effort and supports GIF, APNG, and WebP. If you want to explicitly bypass Image Optimization for a given animated image, use theunoptimizedprop.

For an overview of the Image component features and usage guidelines, see:

# next/image

# 已知的浏览器Bug

# 必须的 Props

# src

# width

# height

# alt

# 可选的 Props

# loader

# fill

# sizes

# quality

# priority

# placeholder

# Advanced Props

# style

# onLoadingComplete

# onLoad

# onError

# loading

# blurDataURL

# unoptimized

# Other Props

# 配置选项

# 远程模式

# Domains

# Loader Configuration

# Advanced

# Device Sizes

# Image Sizes

# Acceptable Formats

# 缓存行为

# Minimum Cache TTL

# Disable Static Imports

# Dangerously Allow SVG

# Animated Images

# Related

next/image

已知的浏览器Bug

必须的 Props

src

width

height

alt

可选的 Props

loader

fill

sizes

quality

priority

placeholder

Advanced Props

style

onLoadingComplete

onLoad

onError

loading

blurDataURL

unoptimized

Other Props

配置选项

远程模式

Domains

Loader Configuration

Advanced

Device Sizes

Image Sizes

Acceptable Formats

缓存行为

Minimum Cache TTL

Disable Static Imports

Dangerously Allow SVG

Animated Images

Related