<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

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

'use client'

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

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

sizes 属性在图片性能方面有两个重要作用：

1. 浏览器使用 sizes 的值从 next/image 自动生成的 srcset 中选择要下载的图片尺寸。当浏览器选择时，它还不知道图片在页面上的实际大小，因此会选择与视口相同或更大的图片。sizes 属性允许您告诉浏览器图片实际上会比全屏小。如果未在带有 fill 属性的图片中指定 sizes 值，则默认使用 100vw（全屏宽度）。

2. sizes 属性会改变自动生成的 srcset 的行为。如果没有 sizes 值，会生成一个适合固定大小图片的小 srcset（1x/2x 等）。如果定义了 sizes，则会生成一个适合响应式图片的大 srcset（640w/750w 等）。如果 sizes 属性包含如 50vw 这样的值，表示视口宽度的百分比，那么 srcset 会被修剪，不包含任何可能过小的值。

例如，如果您知道您的样式会使图片在移动设备上全宽显示，在平板电脑上显示为两列布局，在桌面显示器上显示为三列布局，则应包含如下 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。

priority

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

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

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

仅当图片在首屏可见时使用。默认为 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

'use client'

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

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

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

onLoad

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

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

加载事件可能发生在图片占位符移除和图片完全解码之前。如果您想等待图片完全加载，请改用 onLoadingComplete。

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

其他属性

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

• srcSet。请改用 设备尺寸 (Device Sizes)。
• decoding。始终为 "async"。

配置选项

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

remotePatterns

为防止恶意用户攻击您的应用，使用外部图像需进行配置。这确保只有来自您账户的外部图像可以通过 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。

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

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

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

domains

警告：建议配置严格的 remotePatterns 而非 domains，以保护应用免受恶意用户攻击。仅当您拥有该域名下的所有内容时才使用 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 应用的根目录。该文件必须导出一个返回字符串的默认函数，例如：

'use client'

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 属性指定图像宽度列表。这些宽度与 设备尺寸 (deviceSizes) 数组拼接，形成用于生成图像 srcset 的完整尺寸数组。

之所以分为两个单独的列表，是因为 imageSizes 仅用于提供 sizes 属性的图像，表明图像小于屏幕的全宽。因此，imageSizes 中的尺寸都应小于 deviceSizes 中的最小尺寸。

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

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

formats

默认的 图像优化 API (Image Optimization 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 标头。

缓存行为

以下描述了默认 加载器 (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)，单位为秒。在许多情况下，最好使用 静态图像导入 (Static Image Import)，它会自动对文件内容进行哈希处理，并使用 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 相同的功能，如果没有适当的 内容安全策略 (Content Security Policy)，可能导致漏洞。

如果需要使用默认的图像优化 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: '500px', height: '300px' }}>
      <Image
        src={photoUrl}
        alt="作者照片"
        sizes="500px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

尝试以下示例：

• 演示 fill 属性

主题检测

若需为浅色和深色模式显示不同的图片，您可以创建一个新组件来包裹两个 <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"。

尝试以下示例：

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

已知浏览器问题

next/image 组件使用浏览器原生 延迟加载 (lazy loading)，对于 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

版本历史