Menu

图像

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="Picture of the author"
    />
  )
}

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

参考

Props

以下是可用的 props：

Prop示例类型状态
srcsrc="/profile.png"String必需
altalt="Picture of the author"String必需
widthwidth={500}Integer (px)-
heightheight={500}Integer (px)-
fillfill={true}Boolean-
loaderloader={imageLoader}Function-
sizessizes="(max-width: 768px) 100vw, 33vw"String-
qualityquality={80}Integer (1-100)-
preloadpreload={true}Boolean-
placeholderplaceholder="blur"String-
stylestyle={{objectFit: "contain"}}Object-
onLoadingCompleteonLoadingComplete={img => done())}Function已弃用
onLoadonLoad={event => done())}Function-
onErroronError(event => fail()}Function-
loadingloading="lazy"String-
blurDataURLblurDataURL="data:image/jpeg..."String-
unoptimizedunoptimized={true}Boolean-
overrideSrcoverrideSrc="/seo.png"String-
decodingdecoding="async"String-

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} />
}

值得注意的是：出于安全考虑，使用默认 loader 的 Image Optimization API 在获取 src 图片时不会转发请求头。 如果 src 图片需要身份验证，请考虑使用 unoptimized 属性来禁用图片优化。

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

Object Fit：

如果没有对图片应用样式，图片将拉伸以适应容器。你可以使用 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="Picture of the author"
      width={500}
      height={500}
    />
  )
}

或者，你可以在 next.config.js 中使用 loaderFile 配置来配置应用中每个 next/image 实例，而无需传递 prop。

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 prop
  • 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 prop 设置自定义宽度，请确保同时设置 height: 'auto' 以保持图片的宽高比。

preload

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

// 默认 preload 是 false
<Image preload={false} />
  • true：通过在 <head> 中插入 <link> 来预加载图片。
  • false：不预加载图片。

何时使用：

  • 图片是 Largest Contentful Paint (LCP) 元素。
  • 图片在首屏上方，通常是主图。
  • 你希望在 <head> 中开始加载图片，而不是在 <body> 中稍后才发现它。

何时不使用：

  • 当你有多个图片可能被视为 Largest Contentful Paint (LCP) 元素（取决于视口）时。
  • 当使用 loading 属性时。
  • 当使用 fetchPriority 属性时。

在大多数情况下，你应该使用 loading="eager" 或 fetchPriority="high" 而不是 preload。

priority

从 Next.js 16 开始，priority 属性已被弃用，改为使用 preload 属性，以使行为更加清晰。

loading

控制图片何时开始加载。

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

仅当你想确保图片立即加载时才使用 eager。

了解更多关于 loading 属性。

placeholder

指定在图片加载时使用的占位符，改善感知加载性能。

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

示例：

了解更多关于 placeholder 属性。

blurDataURL

一个 Data 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 将此 prop 分配给所有图片：

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

overrideSrc

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

input.js
<Image src="/profile.jpg" />
output.html
<img
  srcset="
    /_next/image?url=%2Fprofile.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fprofile.jpg&w=828&q=75 2x
  "
  src="/_next/image?url=%2Fprofile.jpg&w=828&q=75"
/>

在某些情况下，不希望生成 src 属性，你可能希望使用 overrideSrc prop 覆盖它。

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

input.js
<Image src="/profile.jpg" overrideSrc="/override.jpg" />
output.html
<img
  srcset="
    /_next/image?url=%2Fprofile.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fprofile.jpg&w=828&q=75 2x
  "
  src="/override.jpg"
/>

decoding

向浏览器提示是否应该等待图片解码后再呈现其他内容更新。

// 默认是 async
<Image decoding="async" />
  • async：异步解码图片，并允许在完成之前渲染其他内容。
  • sync：同步解码图片，以便与其他内容一起原子呈现。
  • auto：无偏好。浏览器选择最佳方法。

了解更多关于 decoding 属性。

其他 Props

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

已弃用的 props

onLoadingComplete

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

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

回调函数将使用一个参数调用，该参数是对底层 <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 Bad Request 错误。

值得注意的是：省略 search 属性允许所有搜索参数，这可能允许恶意行为者优化你不打算优化的 URL。尝试使用特定值，如 search: '?v=2' 以确保精确匹配。

remotePatterns

在你的 next.config.js 文件中使用 remotePatterns 来允许从特定外部路径优化图片并阻止所有其他路径。这确保只能提供来自你账户的外部图片。

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

你也可以使用对象配置 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 Bad Request。

通配符模式：

通配符模式可用于 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 Bad Request。

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 prop 来配置 next/image 的每个实例。

path

如果你想更改或为 Image Optimization API 添加前缀，可以使用 path 属性来实现。path 的默认值是 /_next/image。

next.config.js
module.exports = {
  images: {
    path: '/my-prefix/_next/image',
  },
}

deviceSizes

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

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

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

imageSizes

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

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

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

imageSizes 仅用于提供 sizes prop 的图片，这表明图片小于屏幕的全宽。因此，imageSizes 中的大小应该都小于 deviceSizes 中的最小大小。

qualities

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

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

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

值得注意的是：从 Next.js 16 开始，此字段是必需的，因为不受限制的访问可能允许恶意行为者优化比你预期更多的质量。

你可以向允许列表添加更多图片质量，例如以下内容：

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

在上面的示例中，只允许四个质量：25、50、75 和 100。

如果 quality prop 与此数组中的值不匹配，将使用最接近的允许值。

如果直接访问 REST API 时使用的质量与此数组中的值不匹配，服务器将返回 400 Bad Request 响应。

formats

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

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

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

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

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

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

值得注意的是：

  • 我们仍然建议在大多数用例中使用 WebP。
  • AVIF 编码通常需要 50% 更长的时间，但与 WebP 相比压缩小 20%。这意味着第一次请求图片时通常会更慢，但后续缓存的请求会更快。
  • 如果你在 Next.js 前面使用 Proxy/CDN 进行自托管，则必须配置 Proxy 以转发 Accept 标头。

minimumCacheTTL

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

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

next.config.js
module.exports = {
  images: {
    minimumCacheTTL: 14400, // 4 小时
  },
}

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

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

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

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

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

disableStaticImages

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

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

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

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

maximumRedirects

默认图片优化加载器在获取远程图片时将跟随 HTTP 重定向最多 3 次。

next.config.js
module.exports = {
  images: {
    maximumRedirects: 3,
  },
}

你可以配置获取远程图片时要跟随的重定向次数。将值设置为 0 将禁用跟随重定向。

next.config.js
module.exports = {
  images: {
    maximumRedirects: 0,
  },
}

dangerouslyAllowLocalIP

在极少数情况下，当在私有网络上自托管 Next.js 时，你可能希望允许优化来自同一网络上本地 IP 地址的图片。这不推荐用于大多数用户，因为它可能允许恶意用户访问内部网络上的内容。

默认情况下，该值为 false。

next.config.js
module.exports = {
  images: {
    dangerouslyAllowLocalIP: false,
  },
}

如果你需要优化托管在本地网络其他地方的远程图片，可以将值设置为 true。

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

dangerouslyAllowSVG

dangerouslyAllowSVG 允许你提供 SVG 图片。

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

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

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

我们建议当 src prop 已知为 SVG 时使用 unoptimized prop。当 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',
  },
}

contentSecurityPolicy

contentSecurityPolicy 允许你为图片配置 Content-Security-Policy 标头。这在使用 dangerouslyAllowSVG 时特别重要，可以防止图片中嵌入的脚本执行。

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

默认情况下，loader 将 Content-Disposition 标头设置为 attachment 以提供额外保护，因为 API 可以提供任意远程图片。

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

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

已弃用的配置选项

domains

警告：自 Next.js 14 起已弃用，改为使用严格的 remotePatterns 以保护你的应用程序免受恶意用户的攻击。

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

由于大多数远程图片服务器在多个租户之间共享，因此使用 remotePatterns 更安全，以确保只优化预期的图片。

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

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

函数

getImageProps

getImageProps 函数可用于获取将传递给底层 <img> 元素的 props，而不是将它们传递给另一个组件、样式、画布等。

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 prop 一起使用，因为占位符永远不会被移除。

已知的浏览器错误

此 next/image 组件使用浏览器原生延迟加载，对于 Safari 15.4 之前的旧浏览器，可能会回退到急切加载。当使用模糊占位符时，Safari 12 之前的旧浏览器将回退到空占位符。当使用 width/height 为 auto 的样式时，可能会在 Safari 15 之前不保持宽高比的旧浏览器上导致布局偏移。有关更多详细信息，请参阅此 MDN 视频。

示例

样式图片

样式化 Image 组件类似于样式化普通 <img> 元素，但有一些指南需要记住：

使用 className 或 style，而不是 styled-jsx。在大多数情况下，我们建议使用 className prop。这可以是导入的 CSS Module、全局样式表等。

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

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

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 会根据文件自动设置其宽度和高度。你可以通过设置样式使图片响应式：

Responsive image filling the width and height of its parent container
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 props，以便 Next.js 可以计算宽高比：

components/page.js
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 prop 并将 objectFit prop 设置为 cover。这将使图片填充其父容器的全宽。

Grid of images filling parent container width
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 prop 使图片覆盖整个屏幕区域：

Background image taking full width and height of page
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="Picture of the author"
      width={500}
      height={500}
    />
  )
}

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

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;
  }
}
components/theme-image.tsx
TypeScript
import styles from './theme-image.module.css'
import Image, { ImageProps } from 'next/image'
 
type Props = Omit<ImageProps, 'src' | 'preload' | '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" 的默认行为确保只加载正确的图片。你不能使用 preload 或 loading="eager"，因为这会导致两个图片都被加载。相反，你可以使用 fetchPriority="high"。

试一试：

艺术方向

如果你想为移动端和桌面端显示不同的图片，有时称为艺术方向，你可以向 getImageProps() 提供不同的 src、width、height 和 quality props。

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

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>
  )
}

版本历史

版本变化
v16.0.0qualities 默认配置更改为 [75]，添加了 preload prop，弃用了 priority prop，添加了 dangerouslyAllowLocalIP 配置，添加了 maximumRedirects 配置。
v15.3.0remotePatterns 添加了对 URL 对象数组的支持。
v15.0.0contentDispositionType 配置默认值更改为 attachment。
v14.2.23添加了 qualities 配置。
v14.2.15添加了 decoding prop 和 localPatterns 配置。
v14.2.14添加了 remotePatterns.search prop。
v14.2.0添加了 overrideSrc prop。
v14.1.0getImageProps() 稳定。
v14.0.0弃用了 onLoadingComplete prop 和 domains 配置。
v13.4.14placeholder prop 支持 data:/image...
v13.2.0添加了 contentDispositionType 配置。
v13.0.6添加了 ref prop。
v13.0.0next/image 导入重命名为 next/legacy/image。next/future/image 导入重命名为 next/image。提供了代码转换工具以安全自动地重命名你的导入。移除了 <span> 包装器。移除了 layout、objectFit、objectPosition、lazyBoundary、lazyRoot props。alt 是必需的。onLoadingComplete 接收对 img 元素的引用。移除了内置加载器配置。
v12.3.0remotePatterns 和 unoptimized 配置稳定。
v12.2.0添加了实验性的 remotePatterns 和实验性的 unoptimized 配置。移除了 layout="raw"。
v12.1.1添加了 style prop。添加了对 layout="raw" 的实验性支持。
v12.1.0添加了 dangerouslyAllowSVG 和 contentSecurityPolicy 配置。
v12.0.9添加了 lazyRoot prop。
v12.0.0添加了 formats 配置。
添加了 AVIF 支持。
包装器 <div> 更改为 <span>。
v11.1.0添加了 onLoadingComplete 和 lazyBoundary props。
v11.0.0src prop 支持静态导入。
添加了 placeholder prop。
添加了 blurDataURL prop。
v10.0.5添加了 loader prop。
v10.0.1添加了 layout prop。
v10.0.0引入 next/image。