<Image>

须知：如果您使用的是 Next.js 13 之前的版本，请查阅 next/legacy/image 文档，因为该组件已重命名。

本 API 参考将帮助您理解如何使用图片组件的 属性 和 配置选项。关于功能和用法，请参阅 图片组件 页面。

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="作者照片"
    />
  )
}

属性

以下是图片组件可用的属性概览：

必填属性

图片组件需要以下属性：src、width、height 和 alt。

import Image from 'next/image'

export default function Page() {
  return (
    <div>
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="作者照片"
      />
    </div>
  )
}

src

必须是以下之一：

• 静态导入 的图片文件
• 路径字符串。可以是绝对外部 URL，或根据 loader 属性决定的内部路径。

使用外部 URL 时，必须将其添加到 next.config.js 中的 remotePatterns。

width

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

必填，除非是 静态导入的图片 或使用了 fill 属性 的图片。

height

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

必填，除非是 静态导入的图片 或使用了 fill 属性 的图片。

alt

alt 属性用于为屏幕阅读器和搜索引擎描述图片。如果图片被禁用或加载出错，它也是回退文本。

应包含可以替代图片 而不改变页面含义 的文本。它不应补充图片信息，也不应重复图片上方或下方标题中已提供的信息。

如果图片是 纯装饰性 或 非用户意图 的，alt 属性应为空字符串 (alt="")。

了解更多

可选属性

<Image /> 组件接受许多除必填属性外的附加属性。本节介绍图片组件最常用的属性。更多不常用的属性详情请参阅 高级属性 部分。

loader

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

loader 是一个返回图片 URL 字符串的函数，接受以下参数：

• src
• width
• quality

以下是使用自定义加载器的示例：

import Image from 'next/image'

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

export default function Page() {
  return (
    <Image
      loader={imageLoader}
      src="me.png"
      alt="作者照片"
      width={500}
      height={500}
    />
  )
}

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

fill

fill={true} // {true} | {false}

一个布尔值，使图片填充父元素，这在 width 和 height 未知时非常有用。

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

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

如果没有对图片应用样式，图片将拉伸以填充容器。您可能更喜欢设置 object-fit: "contain" 以使图片适应容器并保留宽高比。

或者，object-fit: "cover" 将使图片填充整个容器并裁剪以保留宽高比。为了使此效果正确，应将 overflow: "hidden" 样式分配给父元素。

更多信息，请参阅：

• position
• object-fit
• object-position

sizes

一个类似于媒体查询的字符串，提供有关图片在不同断点下的宽度信息。sizes 的值将极大地影响使用 fill 或 设置为响应式大小 的图片的性能。

sizes 属性有两个与图片性能相关的重要用途：

• 首先，浏览器使用 sizes 的值从 next/image 自动生成的 srcset 中选择要下载的图片大小。当浏览器选择时，它还不知道页面上图片的大小，因此它会选择与视口相同或更大的图片。sizes 属性允许您告诉浏览器图片实际上会比全屏小。如果在具有 fill 属性的图片中未指定 sizes 值，则使用默认值 100vw（全屏宽度）。
• 其次，sizes 属性改变了自动生成的 srcset 值的行为。如果没有 sizes 值，则生成一个小的 srcset，适合固定大小的图片（1x/2x 等）。如果定义了 sizes，则生成一个大的 srcset，适合响应式图片（640w/750w 等）。如果 sizes 属性包含诸如 50vw 这样的值，表示视口宽度的百分比，则 srcset 会被修剪，不包含任何可能永远不需要的小值。

例如，如果您知道您的样式会使图片在移动设备上全宽，在平板电脑上为 2 列布局，在桌面显示器上为 3 列布局，则应包含如下 sizes 属性：

import Image from 'next/image'

export default function Page() {
  return (
    <div className="grid-element">
      <Image
        fill
        src="/example.png"
        sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
      />
    </div>
  )
}

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

了解更多关于 srcset 和 sizes：

• web.dev
• mdn

quality

quality={75} // {number 1-100}

优化图片的质量，介于 1 和 100 之间的整数，其中 100 是质量最好且文件最大的。默认为 75。

如果在 next.config.js 中定义了 qualities 配置，quality 属性必须与配置中定义的值之一匹配。

须知：如果原始源图片质量已经很低，将 quality 属性设置得太高可能会导致优化后的图片比原始源图片更大。

priority

priority={false} // {false} | {true}

当为 true 时，图片将被视为高优先级并 预加载。使用 priority 的图片会自动禁用懒加载。

您应在检测为 最大内容绘制 (LCP) 元素的任何图片上使用 priority 属性。可能有多个优先级图片是合适的，因为不同的图片可能是不同视口大小的 LCP 元素。

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

placeholder

placeholder = 'empty' // "empty" | "blur" | "data:image/..."

图片加载时使用的占位符。可能的值为 blur、empty 或 data:image/...。默认为 empty。

当为 blur 时，将使用 blurDataURL 属性作为占位符。如果 src 是 静态导入 的对象且导入的图片是 .jpg、.png、.webp 或 .avif，则 blurDataURL 将自动填充，除非检测到图片是动画的。

对于动态图片，您必须提供 blurDataURL 属性。诸如 Plaiceholder 的解决方案可以帮助生成 base64。

当为 data:image/... 时，Data URL 将用作图片加载时的占位符。

当为 empty 时，图片加载时将没有占位符，只有空白空间。

尝试一下：

• 演示 blur 占位符
• 演示使用 data URL placeholder 属性的微光效果
• 演示使用 blurDataURL 属性的颜色效果

高级属性

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

style

允许将 CSS 样式传递给底层图片元素。

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
}

export default function ProfileImage() {
  return <Image src="..." style={imageStyle} />
}

请记住，必填的 width 和 height 属性可能与您的样式交互。如果您使用样式修改图片的宽度，还应将其高度样式设置为 auto 以保留其固有宽高比，否则图片会变形。

onLoadingComplete

<Image onLoadingComplete={(img) => console.log(img.naturalWidth)} />

警告：自 Next.js 14 起已弃用，推荐使用 onLoad。

图片完全加载且 占位符 移除后调用的回调函数。

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

onLoad

<Image onLoad={(e) => console.log(e.target.naturalWidth)} />

图片完全加载且 占位符 移除后调用的回调函数。

回调函数将使用一个参数调用，即事件，其 target 引用底层 <img> 元素。

onError

<Image onError={(e) => console.error(e.target.id)} />

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

loading

推荐：此属性仅适用于高级用例。将图片加载方式切换为 eager 通常会损害性能。我们建议改用 priority 属性，该属性会主动预加载图片。

loading = 'lazy' // {lazy} | {eager}

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

当设置为 lazy 时，延迟加载图片，直到其到达与视口的计算距离。

当设置为 eager 时，立即加载图片。

了解更多关于 loading 属性。

blurDataURL

一个 Data URL，用于在 src 图片成功加载前作为占位图片。仅在与 placeholder="blur" 结合使用时生效。

必须是一个 base64 编码的图片。它会被放大并模糊处理，因此建议使用非常小的图片（10px 或更小）。包含较大的图片作为占位符可能会损害应用性能。

尝试以下示例：

• 演示默认 blurDataURL 属性
• 演示带 blurDataURL 属性的颜色效果

你也可以生成纯色 Data URL 以匹配图片颜色。

unoptimized

unoptimized = {false} // {false} | {true}

当为 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,
  },
}

overrideSrc

当向 <Image> 组件提供 src 属性时，生成的 <img> 会自动生成 srcset 和 src 属性。

<Image src="/me.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/_next/image?url=%2Fme.jpg&w=828&q=75"
/>

在某些情况下，可能不希望生成 src 属性，而希望通过 overrideSrc 属性覆盖它。

例如，当从 <img> 升级到 <Image> 时，可能希望保持相同的 src 属性以用于 SEO 目的，如图片排名或避免重新抓取。

<Image src="/me.jpg" overrideSrc="/override.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/override.jpg"
/>

decoding

提示浏览器是否应等待图片解码完成后再呈现其他内容更新。默认为 async。

可能的取值如下：

• async - 异步解码图片，允许其他内容在解码完成前渲染。
• sync - 同步解码图片，与其他内容一起原子性呈现。
• auto - 不指定解码模式，由浏览器决定最佳方式。

了解更多关于 decoding 属性。

其他属性

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

• srcSet。请改用 设备尺寸。

配置选项

除了属性外，还可以在 next.config.js 中配置图片组件。以下是可用的选项：

localPatterns

可以在 next.config.js 文件中可选地配置 localPatterns，以允许优化特定路径并阻止所有其他路径。

module.exports = {
  images: {
    localPatterns: [
      {
        pathname: '/assets/images/**',
        search: '',
      },
    ],
  },
}

须知：以上示例确保 next/image 的 src 属性必须以 /assets/images/ 开头且不能有查询字符串。尝试优化任何其他路径将返回 400 Bad Request。

remotePatterns

为了保护应用免受恶意用户攻击，使用外部图片需要配置。这确保只有来自你账户的外部图片可以通过 Next.js 图片优化 API 提供。这些外部图片可以在 next.config.js 文件中通过 remotePatterns 属性配置，如下所示：

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

须知：以上示例确保 next/image 的 src 属性必须以 https://example.com/account123/ 开头且不能有查询字符串。任何其他协议、主机名、端口或不匹配的路径将返回 400 Bad Request。

以下是 next.config.js 文件中使用 hostname 通配符模式的 remotePatterns 属性示例：

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

须知：以上示例确保 next/image 的 src 属性必须以 https://img1.example.com 或 https://me.avatar.example.com 或任意数量的子域名开头。不能有端口或查询字符串。任何其他协议或不匹配的主机名将返回 400 Bad Request。

通配符模式可用于 pathname 和 hostname，语法如下：

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

** 语法不能在模式中间使用。

须知：当省略 protocol、port、pathname 或 search 时，默认为通配符 **。这不推荐，因为它可能允许恶意用户优化你不希望优化的 URL。

以下是 next.config.js 文件中使用 search 的 remotePatterns 属性示例：

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

须知：以上示例确保 next/image 的 src 属性必须以 https://assets.example.com 开头且必须有精确的查询字符串 ?v=1727111025337。任何其他协议或查询字符串将返回 400 Bad Request。

domains

警告：自 Next.js 14 起已弃用，推荐使用严格的 remotePatterns 以保护应用免受恶意用户攻击。仅在你拥有该域名下所有内容时使用 domains。

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

然而，domains 配置不支持通配符模式匹配，也无法限制协议、端口或路径名。

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

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

loaderFile

如果你想使用云提供商优化图片而非 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}`
}

或者，你可以使用 loader 属性 为每个 next/image 实例单独配置。

示例：

• 自定义图片加载器配置

高级配置

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

deviceSizes

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

如果未提供配置，则使用以下默认值。

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

imageSizes

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

之所以有两个单独的列表，是因为 imageSizes 仅用于提供 sizes 属性的图片，表示图片小于屏幕的完整宽度。因此，imageSizes 中的尺寸都应小于 deviceSizes 中的最小尺寸。

如果未提供配置，则使用以下默认值。

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

qualities

默认的 图片优化 API 会自动允许 1 到 100 的所有质量值。如果希望限制允许的质量值，可以在 next.config.js 中添加配置。

module.exports = {
  images: {
    qualities: [25, 50, 75],
  },
}

在上面的示例中，仅允许三种质量值：25、50 和 75。如果 quality 属性不匹配此数组中的值，图片将返回 400 Bad Request。

formats

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

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

如果未提供配置，则使用以下默认值。

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

可以通过以下配置启用 AVIF 支持。

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

须知：

• AVIF 通常编码时间比 WebP 长 20%，但压缩率比 WebP 高 20%。这意味着首次请求图片时通常较慢，但后续缓存的请求会更快。
• 如果在 Next.js 前使用代理/CDN 自托管，必须配置代理转发 Accept 头。

缓存行为

以下描述了默认 加载器 的缓存算法。对于其他加载器，请参考云提供商的文档。

图片在请求时动态优化并存储在 <distDir>/cache/images 目录中。优化后的图片文件将用于后续请求，直到过期。当请求匹配缓存但已过期的文件时，立即返回过期的图片。然后在后台重新优化图片（也称为重新验证）并使用新的过期日期保存到缓存中。

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

• MISS - 路径不在缓存中（最多发生一次，首次访问时）
• STALE - 路径在缓存中但已超过重新验证时间，将在后台更新
• HIT - 路径在缓存中且未超过重新验证时间

过期时间（或最大年龄）由 minimumCacheTTL 配置或上游图片的 Cache-Control 头决定，取较大值。具体来说，使用 Cache-Control 头的 max-age 值。如果同时找到 s-maxage 和 max-age，则优先使用 s-maxage。max-age 也会传递给任何下游客户端，包括 CDN 和浏览器。

• 可以配置 minimumCacheTTL 在上游图片不包含 Cache-Control 头或值非常低时增加缓存时间。
• 可以配置 deviceSizes 和 imageSizes 以减少可能生成的图片总数。
• 可以配置 formats 禁用多种格式，仅使用单一图片格式。

minimumCacheTTL

可以配置缓存优化图片的生存时间（TTL，秒）。在许多情况下，最好使用 静态图片导入，它会自动哈希文件内容并使用 Cache-Control 头 immutable 永久缓存图片。

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

优化图片的过期时间（或最大年龄）由 minimumCacheTTL 或上游图片的 Cache-Control 头决定，取较大值。

如果需要按图片更改缓存行为，可以配置 headers 在上游图片（例如 /some-asset.jpg，而非 /_next/image 本身）上设置 Cache-Control 头。

目前没有机制可以手动使缓存失效，因此最好将 minimumCacheTTL 设置为较低值。否则可能需要手动更改 src 属性或删除 <distDir>/cache/images。

disableStaticImages

默认行为允许导入静态文件，如 import icon from './icon.png'，然后将其传递给 src 属性。

在某些情况下，如果与其他期望导入行为不同的插件冲突，可能希望禁用此功能。

可以在 next.config.js 中禁用静态图片导入：

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

dangerouslyAllowSVG

默认的 loader 出于几个原因不会优化 SVG 图像。首先，SVG 是一种矢量格式，意味着它可以无损调整大小。其次，SVG 具有许多与 HTML/CSS 相同的特性，若没有正确的 内容安全策略 (CSP) 标头，可能会导致安全漏洞。

因此，当已知 src 属性为 SVG 时，我们建议使用 unoptimized 属性。当 src 以 ".svg" 结尾时，此操作会自动执行。

但如果您需要使用默认的图像优化 API 提供 SVG 图像，可以在 next.config.js 中设置 dangerouslyAllowSVG：

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

此外，强烈建议同时设置 contentDispositionType 以强制浏览器下载图像，并设置 contentSecurityPolicy 以防止嵌入在图像中的脚本执行。

动画图像

默认的 loader 会自动绕过动画图像的图像优化，并按原样提供图像。

对动画文件的自动检测是尽力而为的，支持 GIF、APNG 和 WebP。如果您想明确绕过特定动画图像的图像优化，请使用 unoptimized 属性。

响应式图像

默认生成的 srcset 包含 1x 和 2x 图像，以支持不同的设备像素密度。然而，您可能希望渲染一个随视口拉伸的响应式图像。在这种情况下，您需要设置 sizes 以及 style（或 className）。

您可以使用以下方法之一渲染响应式图像。

使用静态导入的响应式图像

如果源图像不是动态的，您可以静态导入以创建响应式图像：

import Image from 'next/image'
import me from '../photos/me.jpg'

export default function Author() {
  return (
    <Image
      src={me}
      alt="作者照片"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
    />
  )
}

尝试一下：

• 演示图像随视口响应

带有宽高比的响应式图像

如果源图像是动态的或远程 URL，您还需要提供 width 和 height 以设置响应式图像的正确宽高比：

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <Image
      src={photoUrl}
      alt="作者照片"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
      width={500}
      height={300}
    />
  )
}

尝试一下：

• 演示图像随视口响应

使用 fill 的响应式图像

如果您不知道宽高比，则需要设置 fill 属性并在父元素上设置 position: relative。可选地，您可以根据所需的拉伸或裁剪行为设置 object-fit 样式：

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <div style={{ position: 'relative', width: '300px', height: '500px' }}>
      <Image
        src={photoUrl}
        alt="作者照片"
        sizes="300px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

尝试一下：

• 演示 fill 属性

主题检测 CSS

如果您希望在浅色和深色模式下显示不同的图像，可以创建一个新组件，包装两个 <Image> 组件，并根据 CSS 媒体查询显示正确的图像。

.imgDark {
  display: none;
}

@media (prefers-color-scheme: dark) {
  .imgLight {
    display: none;
  }
  .imgDark {
    display: unset;
  }
}

import styles from './theme-image.module.css'
import Image, { ImageProps } from 'next/image'

type Props = Omit<ImageProps, 'src' | 'priority' | 'loading'> & {
  srcLight: string
  srcDark: string
}

const ThemeImage = (props: Props) => {
  const { srcLight, srcDark, ...rest } = props

  return (
    <>
      <Image {...rest} src={srcLight} className={styles.imgLight} />
      <Image {...rest} src={srcDark} className={styles.imgDark} />
    </>
  )
}

须知：loading="lazy" 的默认行为确保仅加载正确的图像。您不能使用 priority 或 loading="eager"，因为这会导致两个图像都加载。相反，您可以使用 fetchPriority="high"。

尝试一下：

• 演示浅色/深色模式主题检测

getImageProps

对于更高级的用例，您可以调用 getImageProps() 来获取将传递给底层 <img> 元素的属性，然后将它们传递给另一个组件、样式、画布等。

这也避免了调用 React useState()，因此可以提高性能，但不能与 placeholder 属性一起使用，因为占位符永远不会被移除。

主题检测 Picture

如果您希望在浅色和深色模式下显示不同的图像，可以使用 <picture> 元素根据用户的 首选配色方案 显示不同的图像。

import { getImageProps } from 'next/image'

export default function Page() {
  const common = { alt: '主题示例', width: 800, height: 400 }
  const {
    props: { srcSet: dark },
  } = getImageProps({ ...common, src: '/dark.png' })
  const {
    props: { srcSet: light, ...rest },
  } = getImageProps({ ...common, src: '/light.png' })

  return (
    <picture>
      <source media="(prefers-color-scheme: dark)" srcSet={dark} />
      <source media="(prefers-color-scheme: light)" srcSet={light} />
      <img {...rest} />
    </picture>
  )
}

艺术指导

如果您希望为移动设备和桌面设备显示不同的图像（有时称为 艺术指导），可以为 getImageProps() 提供不同的 src、width、height 和 quality 属性。

import { getImageProps } from 'next/image'

export default function Home() {
  const common = { alt: '艺术指导示例', sizes: '100vw' }
  const {
    props: { srcSet: desktop },
  } = getImageProps({
    ...common,
    width: 1440,
    height: 875,
    quality: 80,
    src: '/desktop.jpg',
  })
  const {
    props: { srcSet: mobile, ...rest },
  } = getImageProps({
    ...common,
    width: 750,
    height: 1334,
    quality: 70,
    src: '/mobile.jpg',
  })

  return (
    <picture>
      <source media="(min-width: 1000px)" srcSet={desktop} />
      <source media="(min-width: 500px)" srcSet={mobile} />
      <img {...rest} style={{ width: '100%', height: 'auto' }} />
    </picture>
  )
}

背景 CSS

您甚至可以将 srcSet 字符串转换为 image-set() CSS 函数，以优化背景图像。

import { getImageProps } from 'next/image'

function getBackgroundImage(srcSet = '') {
  const imageSet = srcSet
    .split(', ')
    .map((str) => {
      const [url, dpi] = str.split(' ')
      return `url("${url}") ${dpi}`
    })
    .join(', ')
  return `image-set(${imageSet})`
}

export default function Home() {
  const {
    props: { srcSet },
  } = getImageProps({ alt: '', width: 128, height: 128, src: '/img.png' })
  const backgroundImage = getBackgroundImage(srcSet)
  const style = { height: '100vh', width: '100vw', backgroundImage }

  return (
    <main style={style}>
      <h1>Hello World</h1>
    </main>
  )
}

已知浏览器问题

此 next/image 组件使用浏览器原生的 懒加载，对于 Safari 15.4 之前的旧浏览器可能会回退到急切加载。当使用模糊占位符时，Safari 12 之前的旧浏览器会回退到空占位符。当使用 width/height 为 auto 的样式时，可能会导致 Safari 15 之前不支持 保留宽高比 的旧浏览器出现 布局偏移 (Layout Shift)。更多详情，请参阅 此 MDN 视频。

• Safari 15 - 16.3 在加载时显示灰色边框。Safari 16.4 修复了此问题。可能的解决方案：
  • 使用 CSS @supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }
  • 如果图像位于首屏，使用 priority
• Firefox 67+ 在加载时显示白色背景。可能的解决方案：
  • 启用 AVIF formats
  • 使用 placeholder

版本历史