Image

须知：如果您使用的 Next.js 版本低于 13，您需要使用 next/legacy/image 文档，因为该组件已重命名。

此 API 参考将帮助您了解如何使用 Image 组件的 属性 和 配置选项。有关功能和用法的更多信息，请参阅Image 组件页面。

import Image from 'next/image'
 
export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
    />
  )
}

属性

以下是 Image 组件可用属性的摘要

必需属性

Image 组件需要以下属性：src、alt、width 和 height（或 fill）。

import Image from 'next/image'
 
export default function Page() {
  return (
    <div>
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="Picture of the author"
      />
    </div>
  )
}

src

必须是以下之一

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

当使用默认 loader 时，也请考虑以下源图片

• 当 src 是外部 URL 时，您还必须配置 remotePatterns
• 当 src 是动画或未知格式（JPEG、PNG、WebP、AVIF、GIF、TIFF）时，图像将按原样提供
• 当 src 是 SVG 格式时，除非启用 unoptimized 或 dangerouslyAllowSVG，否则图像将被阻止

width

width 属性表示图像的固有宽度（以像素为单位）。此属性用于推断图像的正确宽高比，并避免加载期间的布局偏移。它不决定图像的渲染尺寸，渲染尺寸由 CSS 控制，类似于 HTML <img> 标签中的 width 属性。

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

height

height 属性表示图像的固有高度（以像素为单位）。此属性用于推断图像的正确宽高比，并避免加载期间的布局偏移。它不决定图像的渲染尺寸，渲染尺寸由 CSS 控制，类似于 HTML <img> 标签中的 height 属性。

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

须知

• width 和 height 属性结合使用，以确定图像的宽高比，浏览器使用该宽高比在图像加载之前为其预留空间。
• 固有尺寸并不总是意味着浏览器中的渲染尺寸，渲染尺寸将由父容器确定。例如，如果父容器小于固有尺寸，则图像将被缩小以适应容器。
• 当宽度和高度未知时，您可以使用 fill 属性。

alt

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

它应该包含可以替换图像的文本，而不会更改页面的含义。它并非旨在补充图像，不应重复图像上方或下方标题中已提供的信息。

如果图像是纯粹装饰性的或非供用户使用的，则 alt 属性应为空字符串 (alt="")。

了解更多

可选属性

<Image /> 组件接受许多超出必需属性的其他属性。本节介绍 Image 组件最常用的属性。有关较少使用的属性的详细信息，请参阅高级属性部分。

loader

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

loader 是一个函数，它为图像返回 URL 字符串，并提供以下参数

• src
• width
• quality

以下是使用自定义 loader 的示例

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="Picture of the author"
      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" 将使图像填充整个容器并被裁剪以保留宽高比。

有关更多信息，另请参阅

• position
• object-fit
• object-position

sizes

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

sizes 属性服务于与图像性能相关的两个重要目的

• 首先，浏览器使用 sizes 的值来确定要从 next/image 自动生成的 srcset 中下载的图像大小。当浏览器选择时，它还不知道图像在页面上的大小，因此它选择与视口大小相同或更大的图像。sizes 属性允许您告知浏览器图像实际上将小于全屏。如果您未在使用 fill 属性的图像中指定 sizes 值，则使用 100vw（全屏宽度）的默认值。
• 其次，sizes 属性更改自动生成的 srcset 值的行为。如果不存在 sizes 值，则会生成一个小的 srcset，适用于固定尺寸的图像 (1x/2x/etc)。如果定义了 sizes，则会生成一个大的 srcset，适用于响应式图像 (640w/750w/etc)。如果 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 sizes，从服务器选择的图像将是所需宽度的 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 时，Next.js 将预加载图像。对于使用 priority 的图像，将自动禁用懒加载。如果也使用了 loading 属性并将其设置为 lazy，则不能使用 priority 属性。loading 属性仅用于高级用例。当需要 priority 时，请删除 loading。

您应该在任何被检测为最大内容渲染 (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 时，图像加载时将没有占位符，只有空白空间。

体验一下

• 演示模糊占位符
• 演示使用 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)} />

图像完全加载且 占位符 已被移除后，将调用此回调函数。

回调函数将被调用，并带有一个参数，即 Event 对象，该对象具有一个 target 属性，它引用了底层的 <img> 元素。

onError

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

如果图像加载失败，将调用此回调函数。

loading

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 时，源图像将按原样从 src 提供，而不会更改质量、尺寸或格式。默认为 false。

这对于不需要优化的图像很有用，例如小图像（小于 1KB）、矢量图像 (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,
  },
}

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> 时，您可能希望为 SEO 目的（例如图像排名或避免重新抓取）保持相同的 src 属性。

<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 中配置 Image 组件。以下选项可用

localPatterns

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

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

须知：上面的示例将确保 next/image 的 src 属性必须以 /assets/images/ 开头，并且不得包含查询字符串。尝试优化任何其他路径将响应 400 Bad Request。

remotePatterns

为了保护您的应用程序免受恶意用户的攻击，需要配置才能使用外部图像。这确保只有来自您帐户的外部图像才能从 Next.js Image Optimization API 提供。这些外部图像可以使用 next.config.js 文件中的 remotePatterns 属性进行配置，如下所示

module.exports = {
  images: {
    remotePatterns: [new URL('https://example.com/account123/**')],
  },
}

Next.js 15.3.0 之前的版本可以使用对象配置 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 文件中 remotePatterns 属性的示例，其中在 hostname 中使用了通配符模式

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 文件中 remotePatterns 属性的示例，其中使用了 search

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 内置的 Image Optimization 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

默认的 Image Optimization API 将自动允许 1 到 100 之间的所有质量值。如果您希望限制允许的质量值，则可以向 next.config.js 添加配置。

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

在上面的示例中，仅允许三个质量值：25、50 和 75。如果 quality 属性与此数组中的值不匹配，则图像将失败并显示 400 Bad Request。

formats

默认的 Image Optimization API 将自动检测浏览器支持的图像格式，通过请求的 Accept 标头来确定最佳输出格式。

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

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

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

您可以启用 AVIF 支持，如果浏览器 不支持 AVIF，它将回退到 src 图像的原始格式

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

须知:

• 我们仍然建议在大多数情况下使用 WebP。
• AVIF 通常编码时间长 50%，但与 WebP 相比，压缩率高 20%。这意味着首次请求图像时，通常会较慢，然后后续的缓存请求将更快。
• 如果您使用 Proxy/CDN 自托管在 Next.js 前面，则必须配置 Proxy 以转发 Accept 标头。

缓存行为

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

图像在请求时动态优化并存储在 <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 和浏览器。

• 当上游图像不包含 Cache-Control 标头或值非常低时，您可以配置 minimumCacheTTL 以增加缓存持续时间。
• 您可以配置 deviceSizes 和 imageSizes 以减少可能生成的图像总数。
• 您可以配置 formats 以禁用多种格式，而只支持单一图像格式。

minimumCacheTTL

您可以配置缓存优化图像的生存时间 (TTL)，以秒为单位。在许多情况下，最好使用 静态图像导入，这将自动哈希文件内容并将图像永久缓存，并带有 Cache-Control 标头 immutable。

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

module.exports = {
  images: {
    minimumCacheTTL: 60, // 1 minute
  },
}

您可以增加 TTL 以减少重新验证的次数，并有可能降低成本

module.exports = {
  images: {
    minimumCacheTTL: 2678400, // 31 days
  },
}

优化图像的过期时间（或者更确切地说，最大期限）由 minimumCacheTTL 或上游图像 Cache-Control 标头定义，以较大者为准。

如果您需要更改每个图像的缓存行为，您可以配置 headers 以在上游图像上设置 Cache-Control 标头（例如 /some-asset.jpg，而不是 /_next/image 本身）。

目前没有使缓存失效的机制，因此最好保持较低的 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" 结尾时，会自动发生这种情况。

但是，如果您需要使用默认 Image Optimization API 提供 SVG 图像，则可以在 next.config.js 中设置 dangerouslyAllowSVG

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

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

contentDispositionType

默认的 loader 将 Content-Disposition 标头设置为 attachment 以增加保护，因为 API 可以提供任意远程图像。

默认值为 attachment，它强制浏览器在直接访问时下载图像。当 dangerouslyAllowSVG 为 true 时，这一点尤其重要。

您可以选择配置 inline 以允许浏览器在直接访问时呈现图像，而无需下载它。

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

动画图像

默认的 loader 将自动绕过动画图像的 Image Optimization，并按原样提供图像。

动画文件的自动检测是尽力而为的，并支持 GIF、APNG 和 WebP。如果您想为给定的动画图像显式绕过 Image Optimization，请使用 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="Picture of the author"
      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="Picture of the author"
      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="Picture of the author"
        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> 元素的 props，并将其传递给另一个组件、样式、画布等。

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

主题检测图片

如果您想为浅色和深色模式显示不同的图像，您可以使用 <picture> 元素来根据用户的首选颜色方案显示不同的图像。

import { getImageProps } from 'next/image'
 
export default function Page() {
  const common = { alt: 'Theme Example', 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: 'Art Direction Example', 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 之前不支持 保持纵横比 的旧版本浏览器上导致 布局偏移。有关更多详细信息，请参阅 此 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

版本历史