logoNext.js 简体中文
文档博客学习
简介/API 参考文档/组件/图片 (Image)

图片 (Image)

Next.js 的 Image 组件扩展了 HTML <img> 元素，提供自动图像优化功能。

app/page.js
import Image from 'next/image'

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

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

参考

属性

以下是可用的属性：

属性示例类型状态
srcsrc="/profile.png"字符串必需
altalt="作者照片"字符串必需
widthwidth={500}整数 (px)-
heightheight={500}整数 (px)-
fillfill={true}布尔值-
loaderloader={imageLoader}函数-
sizessizes="(max-width: 768px) 100vw, 33vw"字符串-
qualityquality={80}整数 (1-100)-
prioritypriority={true}布尔值-
placeholderplaceholder="blur"字符串-
stylestyle={{objectFit: "contain"}}对象-
onLoadingCompleteonLoadingComplete={img => done())}函数已弃用
onLoadonLoad={event => done())}函数-
onErroronError(event => fail()}函数-
loadingloading="lazy"字符串-
blurDataURLblurDataURL="data:image/jpeg..."字符串-
overrideSrcoverrideSrc="/seo.png"字符串-

src

图像的来源。可以是以下之一：

内部路径字符串。

<Image src="/profile.png" />

绝对外部 URL（必须配置 remotePatterns）。

<Image src="https://example.com/profile.png" />

静态导入。

import profile from './profile.png'

export default function Page() {
  return <Image src={profile} />
}

alt

alt 属性用于为屏幕阅读器和搜索引擎描述图像。如果图像被禁用或加载失败，它也是替代文本。

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

如果图像是纯装饰性的或不面向用户的，alt 属性应为空字符串（alt=""）。

了解更多关于图像无障碍指南。

width 和 height

width 和 height 属性表示图像的固有大小（以像素为单位）。浏览器使用此属性推断正确的宽高比，为图像预留空间并避免加载时的布局偏移。它不控制图像的_渲染大小_，后者由 CSS 控制。

<Image src="/profile.png" width={500} height={500} />

除非满足以下条件，否则必须设置 width 和 height 属性：

如果高度和宽度未知，建议使用 fill 属性。

fill

一个布尔值，使图像扩展到父元素的大小。

<Image src="/profile.png" fill={true} />

定位：

  • 父元素必须设置 position: "relative"、"fixed" 或 "absolute"。
  • 默认情况下，<img> 元素使用 position: "absolute"。

对象适应：

如果没有对图像应用样式，图像将拉伸以填充容器。可以使用 objectFit 控制裁剪和缩放。

  • "contain"：图像将缩小以适应容器并保持宽高比。
  • "cover"：图像将填充容器并被裁剪。

了解更多关于 position 和 object-fit。

loader

用于生成图像 URL 的自定义函数。该函数接收以下参数，并返回图像的 URL 字符串：

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 实例，而无需传递属性。

sizes

定义图像在不同断点处的大小。浏览器使用此属性从生成的 srcset 中选择最合适的尺寸。

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：

  • 图像使用了 fill 属性
  • 使用 CSS 使图像具有响应性

如果缺少 sizes，浏览器会假设图像与视口一样宽（100vw）。这可能导致下载不必要的过大图像。

此外，sizes 会影响 srcset 的生成：

  • 没有 sizes：Next.js 生成有限的 srcset（例如 1x、2x），适合固定大小的图像。
  • 有 sizes：Next.js 生成完整的 srcset（例如 640w、750w 等），针对响应式布局优化。

在 web.dev 和 mdn 上了解更多关于 srcset 和 sizes 的信息。

quality

一个介于 1 和 100 之间的整数，用于设置优化图像的质量。较高的值会增加文件大小和视觉保真度。较低的值会减小文件大小，但可能影响清晰度。

// 默认质量为 75
<Image quality={75} />

如果在 next.config.js 中配置了 qualities，该值必须与允许的条目之一匹配。

须知：如果原始图像质量已经很低，设置高质量值会增加文件大小而不会改善外观。

style

允许向底层图像元素传递 CSS 样式。

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

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

须知：如果使用 style 属性设置自定义宽度，请确保同时设置 height: 'auto' 以保持图像的宽高比。

priority

一个布尔值，指示是否应预加载图像。

// 默认优先级为 false
<Image priority={false} />
  • true：预加载图像。禁用懒加载。
  • false：懒加载图像。

何时使用：

何时不使用：

  • 当使用 loading 属性时（会触发警告）。

loading

控制图像何时开始加载。

// 默认为 lazy
<Image loading="lazy" />
  • lazy：延迟加载图像，直到其到达与视口的计算距离。
  • eager：立即加载图像，无论其在页面中的位置如何。

仅在您希望确保图像立即加载时使用 eager。

了解更多关于 loading 属性。

placeholder

指定在图像加载时使用的占位符，以提高感知加载性能。

// 默认为 empty
<Image placeholder="empty" />
  • empty：图像加载时不显示占位符。
  • blur：使用图像的模糊版本作为占位符。必须与 blurDataURL 属性一起使用。
  • data:image/...：使用数据 URL 作为占位符。

示例：

了解更多关于 placeholder 属性。

blurDataURL

一个数据 URL，用于在图像成功加载之前作为占位符图像。可以自动设置或与 placeholder="blur" 属性一起使用。

<Image placeholder="blur" blurDataURL="..." />

图像会自动放大和模糊，因此建议使用非常小的图像（10px 或更小）。

自动

如果 src 是 jpg、png、webp 或 avif 文件的静态导入，blurDataURL 会自动添加——除非图像是动画的。

手动设置

如果图像是动态的或远程的，您必须自己提供 blurDataURL。要生成一个，可以使用：

较大的 blurDataURL 可能会影响性能。保持其小而简单。

示例：

onLoad

一个回调函数，在图像完全加载且占位符被移除后调用。

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

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

onError

一个回调函数，在图像加载失败时调用。

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

unoptimized

一个布尔值，指示是否应优化图像。这对于无法从优化中受益的图像（如小于 1KB 的小图像、矢量图像 (SVG) 或动画图像 (GIF)）很有用。

import Image from 'next/image'

const UnoptimizedImage = (props) => {
  // 默认为 false
  return <Image {...props} unoptimized />
}
  • true：源图像将从 src 原样提供，而不改变质量、大小或格式。
  • false：源图像将被优化。

自 Next.js 12.3.0 起，可以通过更新 next.config.js 中的以下配置将此属性分配给所有图像：

next.config.js
module.exports = {
  images: {
    unoptimized: true,
  },
}

overrideSrc

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

input.js
<Image src="/profile.jpg" />
output.html
<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 目的，如图像排名或避免重新抓取。

input.js
<Image src="/profile.jpg" overrideSrc="/override.jpg" />
output.html
<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
<Image decoding="async" />
  • async：异步解码图像，并允许其他内容在其完成之前呈现。
  • sync：同步解码图像，与其他内容一起原子呈现。
  • auto：无偏好。浏览器选择最佳方法。

了解更多关于 decoding 属性。

其他属性

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

已弃用的属性

onLoadingComplete

警告：已在 Next.js 14 中弃用，请改用 onLoad。

一个回调函数，当图片完全加载且占位符 (placeholder) 被移除后会被调用。

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

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

配置选项

你可以在 next.config.js 中配置 Image 组件。以下是可用的选项：

localPatterns

在 next.config.js 文件中使用 localPatterns 来允许优化特定本地路径的图片并阻止其他所有路径。

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

上面的示例将确保 next/image 的 src 属性必须以 /assets/images/ 开头且不能有查询字符串。尝试优化其他路径将返回 400 错误请求。

remotePatterns

在 next.config.js 文件中使用 remotePatterns 来允许来自特定外部路径的图片并阻止其他所有路径。这确保只有来自你账户的外部图片可以被服务。

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

如果使用 15.3.0 之前的版本，可以使用对象配置 remotePatterns：

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

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

通配符模式：

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

  • * 匹配单个路径段或子域名
  • ** 匹配任意数量的路径段（末尾）或子域名（开头）。此语法不能在模式中间使用。
next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
        port: '',
        search: '',
      },
    ],
  },
}

这将允许像 image.example.com 这样的子域名。查询字符串和自定义端口仍会被阻止。

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

查询字符串：

你也可以使用 search 属性限制查询字符串：

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

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

loaderFile

loaderFiles 允许你使用自定义图片优化服务替代 Next.js。

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

路径必须相对于项目根目录。文件必须导出一个返回 URL 字符串的默认函数：

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

示例：

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

deviceSizes

deviceSizes 允许你指定设备宽度断点列表。当 next/image 组件使用 sizes 属性时，这些宽度用于确保为用户设备提供正确的图片。

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

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

imageSizes

imageSizes 允许你指定图片宽度列表。这些宽度与设备尺寸 (device sizes) 数组拼接，形成用于生成图片 srcset 的完整尺寸数组。

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

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

imageSizes 仅用于提供 sizes 属性的图片，表示图片小于屏幕的完整宽度。因此，imageSizes 中的所有尺寸应小于 deviceSizes 中的最小尺寸。

qualities

qualities 允许你指定图片质量值列表。

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

在上面的示例中，只允许三种质量：25、50 和 75。如果 quality 属性不匹配此数组中的值，图片将失败并返回 400 错误请求。

formats

formats 允许你指定要使用的图片格式列表。

next.config.js
module.exports = {
  images: {
    // 默认值
    formats: ['image/webp'],
  },
}

Next.js 通过请求的 Accept 标头自动检测浏览器支持的图片格式，以确定最佳输出格式。

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

你可以启用 AVIF 支持，如果浏览器不支持 AVIF，它将回退到源图片的原始格式：

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

须知：

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

minimumCacheTTL

minimumCacheTTL 允许你为缓存的优化图片配置生存时间 (TTL)（以秒为单位）。在许多情况下，最好使用静态图片导入 (Static Image Import)，它会自动哈希文件内容并使用 Cache-Control 标头 immutable 永久缓存图片。

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

next.config.js
module.exports = {
  images: {
    minimumCacheTTL: 60, // 1 分钟
  },
}

你可以增加 TTL 以减少重新验证次数并可能降低成本：

next.config.js
module.exports = {
  images: {
    minimumCacheTTL: 2678400, // 31 天
  },
}

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

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

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

disableStaticImages

disableStaticImages 允许你禁用静态图片导入。

默认行为允许你导入静态文件，例如 import icon from './icon.png'，然后将其传递给 src 属性。在某些情况下，如果与其他插件冲突（这些插件期望导入行为不同），你可能希望禁用此功能。

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

next.config.js
module.exports = {
  images: {
    disableStaticImages: true,
  },
}

dangerouslyAllowSVG

dangerouslyAllowSVG 允许你服务 SVG 图片。

next.config.js
module.exports = {
  images: {
    dangerouslyAllowSVG: true,
  },
}

默认情况下，Next.js 不会优化 SVG 图片，原因如下：

  • SVG 是矢量格式，意味着可以无损调整大小。
  • SVG 具有许多与 HTML/CSS 相同的功能，如果没有适当的内容安全策略 (CSP) 标头，可能导致漏洞。

当 src 属性已知为 SVG 时，我们建议使用 unoptimized 属性。当 src 以 ".svg" 结尾时，这会自动发生。

<Image src="/my-image.svg" unoptimized />

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

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

contentDispositionType

contentDispositionType 允许你配置 Content-Disposition 标头。

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

默认情况下，加载器 (loader) 将 Content-Disposition 标头设置为 attachment 以增加保护，因为 API 可以服务任意远程图片。

默认值为 attachment，强制浏览器在直接访问时下载图片。这在 dangerouslyAllowSVG 为 true 时尤为重要。

你可以选择配置 inline 以允许浏览器在直接访问时渲染图片而无需下载。

已弃用的配置选项

domains

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

类似于 remotePatterns，domains 配置可用于提供允许的外部图片主机名列表。但 domains 配置不支持通配符模式匹配，也无法限制协议、端口或路径名。

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

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

函数

getImageProps

getImageProps 函数可用于获取传递给底层 <img> 元素的属性，并将它们传递给其他组件、样式、画布等。

import { getImageProps } from 'next/image'

const props = getImageProps({
  src: 'https://example.com/image.jpg',
  alt: 'A scenic mountain view',
  width: 1200,
  height: 800,
})

function ImageWithCaption() {
  return (
    <figure>
      <img {...props} />
      <figcaption>A scenic mountain view</figcaption>
    </figure>
  )
}

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

已知浏览器问题

next/image 组件使用浏览器原生的懒加载 (lazy loading)，对于 Safari 15.4 之前的旧浏览器可能会回退到立即加载。当使用模糊占位符时，Safari 12 之前的旧浏览器会回退到空占位符。当使用 width/height 为 auto 的样式时，可能导致 Safari 15 之前不支持保持宽高比 (aspect ratio) 的旧浏览器出现布局偏移 (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+ 在加载时显示白色背景。可能的解决方案：

示例

图片样式

为 Image 组件设置样式与为普通 <img> 元素设置样式类似，但需要记住以下几点：

使用 className 或 style，而不是 styled-jsx。在大多数情况下，我们推荐使用 className 属性。这可以是导入的 CSS 模块 (CSS Module)、全局样式表 (global stylesheet) 等。

import styles from './styles.module.css'

export default function MyImage() {
  return <Image className={styles.image} src="/my-image.png" alt="My Image" />
}

你也可以使用 style 属性来分配内联样式。

export default function MyImage() {
  return (
    <Image style={{ borderRadius: '8px' }} src="/my-image.png" alt="My Image" />
  )
}

当使用 fill 时，父元素必须具有 position: relative 或 display: block。这对于在该布局模式下正确渲染图片元素是必要的。

<div style={{ position: 'relative' }}>
  <Image fill src="/my-image.png" alt="My Image" />
</div>

你不能使用 styled-jsx，因为它的作用域仅限于当前组件（除非你将样式标记为 global）。

静态导出的响应式图片

当导入静态图片时，Next.js 会根据文件自动设置其宽度和高度。您可以通过设置样式使图片具有响应式特性：

响应式图片填满父容器的宽度和高度
import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Responsive() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column' }}>
      <Image
        alt="Mountains"
        // 导入图片将
        // 自动设置宽度和高度
        src={mountains}
        sizes="100vw"
        // 使图片显示为全宽
        // 并保持其宽高比
        style={{
          width: '100%',
          height: 'auto',
        }}
      />
    </div>
  )
}

远程 URL 的响应式图片

如果源图片是动态或远程 URL，您必须提供 width 和 height 属性，以便 Next.js 可以计算宽高比：

components/page.js
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 属性 并将 objectFit 属性设置为 cover。这将使图片填满其父容器的整个宽度。

填满父容器宽度的图片网格
import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Fill() {
  return (
    <div
      style={{
        display: 'grid',
        gridGap: '8px',
        gridTemplateColumns: 'repeat(auto-fit, minmax(400px, auto))',
      }}
    >
      <div style={{ position: 'relative', width: '400px' }}>
        <Image
          alt="Mountains"
          src={mountains}
          fill
          sizes="(min-width: 808px) 50vw, 100vw"
          style={{
            objectFit: 'cover', // cover, contain, none
          }}
        />
      </div>
      {/* 网格中的更多图片... */}
    </div>
  )
}

背景图片

使用 fill 属性使图片覆盖整个屏幕区域：

占据页面全部宽度和高度的背景图片
import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Background() {
  return (
    <Image
      alt="Mountains"
      src={mountains}
      placeholder="blur"
      quality={100}
      fill
      sizes="100vw"
      style={{
        objectFit: 'cover',
      }}
    />
  )
}

有关 Image 组件与各种样式一起使用的示例，请参阅 Image 组件演示。

远程图片

要使用远程图片，src 属性应为 URL 字符串。

app/page.js
import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="https://s3.amazonaws.com/my-bucket/profile.png"
      alt="作者的照片"
      width={500}
      height={500}
    />
  )
}

由于 Next.js 在构建过程中无法访问远程文件，您需要手动提供 width、height 和可选的 blurDataURL 属性。

width 和 height 属性用于推断图片的正确宽高比，并避免图片加载时的布局偏移。width 和 height 并 不 决定图片文件的渲染大小。

为了安全地允许优化图片，请在 next.config.js 中定义支持的 URL 模式列表。尽可能具体以防止恶意使用。例如，以下配置将仅允许来自特定 AWS S3 存储桶的图片：

next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 's3.amazonaws.com',
        port: '',
        pathname: '/my-bucket/**',
        search: '',
      },
    ],
  },
}

主题检测

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

components/theme-image.module.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() 提供不同的 src、width、height 和 quality 属性。

app/page.js
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 函数，以优化背景图片。

app/page.js
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>
  )
}

版本历史

版本变更内容
v15.3.0remotePatterns 新增对 URL 对象数组的支持。
v15.0.0contentDispositionType 配置默认值改为 attachment。
v14.2.23新增 qualities 配置项。
v14.2.15新增 decoding 属性和 localPatterns 配置项。
v14.2.14新增 remotePatterns.search 属性。
v14.2.0新增 overrideSrc 属性。
v14.1.0getImageProps() 进入稳定状态。
v14.0.0弃用 onLoadingComplete 属性和 domains 配置。
v13.4.14placeholder 属性支持 data:/image... 格式。
v13.2.0新增 contentDispositionType 配置项。
v13.0.6新增 ref 属性。
v13.0.0next/image 导入重命名为 next/legacy/image，next/future/image 导入重命名为 next/image。提供 代码迁移工具 用于安全自动重命名导入。移除 <span> 包裹层。移除 layout、objectFit、objectPosition、lazyBoundary、lazyRoot 属性。alt 变为必填项。onLoadingComplete 接收 img 元素引用。移除内置加载器配置。
v12.3.0remotePatterns 和 unoptimized 配置进入稳定状态。
v12.2.0新增实验性 remotePatterns 和实验性 unoptimized 配置。移除 layout="raw"。
v12.1.1新增 style 属性。新增实验性 layout="raw" 支持。
v12.1.0新增 dangerouslyAllowSVG 和 contentSecurityPolicy 配置项。
v12.0.9新增 lazyRoot 属性。
v12.0.0新增 formats 配置项。
新增 AVIF 支持。
外层 <div> 改为 <span>。
v11.1.0新增 onLoadingComplete 和 lazyBoundary 属性。
v11.0.0src 属性支持静态导入。
新增 placeholder 属性。
新增 blurDataURL 属性。
v10.0.5新增 loader 属性。
v10.0.1新增 layout 属性。
v10.0.0引入 next/image。

Head 组件

使用内置的 Head 组件向页面 `head` 添加自定义元素。

Image（旧版）

使用旧版 Image 组件实现向后兼容的图片优化。

On this page