NNext.js 中文网 GitHub

Image(旧版)

legacy

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

从 Next.js 13 开始,next/image 组件被重写,以同时提升性能和开发者体验。为了提供向后兼容的升级方案,旧的 next/image 被重命名为 next/legacy/image。

警告: next/legacy/image 已弃用,并将在 Next.js 的未来版本中移除。请改用 next/image。

对比#

与 next/legacy/image 相比,新的 next/image 组件有以下变化:

  • 移除了 <img> 周围的 <span> 包装器,改用原生计算的宽高比
  • 增加了对规范 style 属性的支持
    • 移除了 layout 属性,改用 style 或 className
    • 移除了 objectFit 属性,改用 style 或 className
    • 移除了 objectPosition 属性,改用 style 或 className
  • 移除了 IntersectionObserver 实现,改用原生懒加载
    • 移除了 lazyBoundary 属性,因为没有对应的原生实现
    • 移除了 lazyRoot 属性,因为没有对应的原生实现
  • 移除了 loader 配置,改用 loader 属性
  • 将 alt 属性从可选改为必填
  • 更改了 onLoadingComplete 回调,使其接收对 <img> 元素的引用

必需属性#

<Image /> 组件需要以下属性。

src#

必须是以下之一:

  • 一个静态导入的图片文件
  • 一个路径字符串。根据 loader 属性或 loader 配置,它可以是绝对外部 URL,也可以是内部路径。

使用默认 loader 时,对于源图片还需考虑以下事项:

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

width#

width 属性可以表示以像素为单位的渲染宽度或原始宽度,具体取决于 layout 和 sizes 属性。

当使用 layout="intrinsic" 或 layout="fixed" 时,width 属性表示以像素为单位的渲染宽度,因此它会影响图片的显示大小。

当使用 layout="responsive"、layout="fill" 时,width 属性表示以像素为单位的原始宽度,因此它只会影响宽高比。

除了静态导入的图片或使用 layout="fill" 的图片外,width 属性都是必需的。

height#

height 属性可以表示以像素为单位的渲染高度或原始高度,具体取决于 layout 和 sizes 属性。

当使用 layout="intrinsic" 或 layout="fixed" 时,height 属性表示以像素为单位的渲染高度,因此它会影响图片的显示大小。

当使用 layout="responsive"、layout="fill" 时,height 属性表示以像素为单位的原始高度,因此它只会影响宽高比。

除了静态导入的图片或使用 layout="fill" 的图片外,height 属性都是必需的。

可选属性#

<Image /> 组件除了必需属性外,还接受一些额外的属性。本节介绍 Image 组件最常用的属性。更多较少使用属性的详细信息,请参见高级属性一节。

layout#

当视口尺寸变化时图片的布局行为。

layout行为srcSetsizes是否有包装器和尺寸调整器
intrinsic (default)缩小以适配容器宽度,最大不超过图片尺寸1x、2x(基于 imageSizes)N/A是
fixed精确调整为 width 和 height 的大小1x、2x(基于 imageSizes)N/A是
responsive缩放以适配容器宽度640w、750w、... 2048w、3840w(基于 imageSizes 和 deviceSizes)100vw是
fill在 X 和 Y 轴方向上拉伸以填充容器640w、750w、... 2048w、3840w(基于 imageSizes 和 deviceSizes)100vw是
  • 演示 intrinsic 布局(默认)
    • 当使用 intrinsic 时,对于较小的视口,图片会缩小尺寸,但对于较大的视口,会保持原始尺寸。
  • 演示 fixed 布局
    • 当使用 fixed 时,图片尺寸不会随视口变化(无响应式),类似于原生 img 元素。
  • 演示 responsive 布局
    • 当使用 responsive 时,对于较小的视口,图片会缩小尺寸,对于较大的视口会放大尺寸。
    • 确保父元素在其样式表中使用 display: block。
  • 演示 fill 布局
    • 当使用 fill 时,如果父元素是相对定位的,图片的宽度和高度都会拉伸到父元素的尺寸。
    • 这通常会与 objectFit 属性配合使用。
    • 确保父元素在其样式表中设置了 position: relative。
  • 演示背景图片

loader#

一个用于解析 URL 的自定义函数。将 loader 设置为 Image 组件上的属性会覆盖 next.config.js 的 images 部分中定义的默认 loader。

loader 是一个函数,给定以下参数后返回图片的 URL 字符串:

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

js
import Image from 'next/legacy/image'

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

const MyImage = (props) => {
  return (
    <Image
      loader={myLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

sizes#

一个字符串,提供有关图片在不同断点处宽度的信息。sizes 的值会极大影响使用 layout="responsive" 或 layout="fill" 的图片的性能。对于使用 layout="intrinsic" 或 layout="fixed" 的图片,它会被忽略。

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

首先,浏览器使用 sizes 的值,从 next/legacy/image 自动生成的源集中确定要下载的图片尺寸。浏览器在选择时还不知道页面上图片的大小,因此它会选择与视口相同或更大的图片。sizes 属性允许你告诉浏览器图片实际上会比全屏小。如果不指定 sizes 值,则使用默认值 100vw(全屏宽度)。

其次,sizes 的值会被解析,用于裁剪自动创建的源集中的值。如果 sizes 属性包含表示视口宽度百分比的尺寸(如 50vw),则会裁剪源集,去除那些过小而不可能用到的值。

例如,如果你知道自己的样式会使图片在移动设备上全宽显示、在平板电脑上以两列布局显示、在桌面显示器上以三列布局显示,就应该包含如下的 sizes 属性:

js
import Image from 'next/legacy/image'
const Example = () => (
  <div className="grid-element">
    <Image
      src="/example.png"
      layout="fill"
      sizes="(max-width: 768px) 100vw,
              (max-width: 1200px) 50vw,
              33vw"
    />
  </div>
)

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

了解更多关于 srcset 和 sizes 的信息:

quality#

优化后图片的质量,是 1 到 100 之间的整数,其中 100 表示最佳质量。默认值为 75。

priority#

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

对于任何被检测为最大内容绘制(Largest Contentful Paint,LCP)元素的图片,都应使用 priority 属性。可能有多个优先级图片是合适的,因为不同的图片可能是不同视口尺寸下的 LCP 元素。

只应在图片位于首屏可见时使用。默认值为 false。

placeholder#

图片加载时使用的占位符。可能的值为 blur 或 empty。默认值为 empty。

当为 blur 时,将使用 blurDataURL 属性作为占位符。如果 src 是来自静态导入的对象,且导入的图片是 .jpg、.png、.webp 或 .avif 格式,则 blurDataURL 会自动填充。

对于动态图片,你必须提供 blurDataURL 属性。Plaiceholder 等解决方案可以帮助生成 base64。

当为 empty 时,图片加载时不会有占位符,只有空白区域。

试一试:

高级属性#

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

style#

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

请注意,所有 layout 模式都会对图片元素应用自己的样式,这些自动样式优先于 style 属性。

还要记住,必需的 width 和 height 属性可能会与你的样式相互影响。如果使用样式修改图片的 width,还必须设置 height="auto" 样式,否则图片会变形。

objectFit#

定义使用 layout="fill" 时图片如何适应其父容器。

该值会传递给 src 图片的 object-fit CSS 属性。

objectPosition#

定义使用 layout="fill" 时图片在其父元素中的定位方式。

该值会传递给应用于图片的 object-position CSS 属性。

onLoadingComplete#

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

onLoadingComplete 函数接受一个参数,即具有以下属性的对象:

loading#

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

当为 lazy 时,延迟加载图片,直到它到达与视口的 计算距离为止。

当为 eager 时,立即加载图片。

了解更多

blurDataURL#

一个Data URL, 用于在 src 图片成功加载之前作为占位图片。只有当与 placeholder="blur"结合使用时才生效。

必须是经过 base64 编码的图片。它会被放大并模糊处理,因此建议使用非常小的图片(10px 或 更小)。使用较大的图片作为占位符可能会损害应用性能。

试一试:

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

lazyBoundary#

一个字符串(语法与 margin 属性类似),作为边界框,用于检测视口与图片的交集并触发懒加载。默认值为 "200px"。

如果图片嵌套在根文档以外的可滚动父元素中,你还需要设置 lazyRoot 属性。

了解更多

lazyRoot#

一个指向可滚动父元素的 React Ref。默认值为 null(文档视口)。

该 Ref 必须指向 DOM 元素,或指向一个将 Ref 转发到底层 DOM 元素的 React 组件。

指向 DOM 元素的示例

jsx
import Image from 'next/legacy/image'
import React from 'react'

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <div ref={lazyRoot} style={{ overflowX: 'scroll', width: '500px' }}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </div>
  )
}

指向 React 组件的示例

jsx
import Image from 'next/legacy/image'
import React from 'react'

const Container = React.forwardRef((props, ref) => {
  return (
    <div ref={ref} style={{ overflowX: 'scroll', width: '500px' }}>
      {props.children}
    </div>
  )
})

const Example = () => {
  const lazyRoot = React.useRef(null)

  return (
    <Container ref={lazyRoot}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </Container>
  )
}

了解更多

unoptimized#

当为 true 时,源图片将直接从 src 按原样提供,而不更改质量、尺寸或格式。默认值为 false。

这对于那些无法从优化中受益的图片很有用,例如小图片(小于 1KB)、矢量图片(SVG)或动画图片(GIF)。

js
import Image from 'next/image'

const UnoptimizedImage = (props) => {
  return <Image {...props} unoptimized />
}

从 Next.js 12.3.0 开始,可以通过使用以下配置更新 next.config.js,将此属性应用于所有图片:

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

其他属性#

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

配置项#

远程模式#

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

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

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

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

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

小知识: 上面的示例将确保 next/legacy/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 的示例:

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

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

域名#

警告: 自 Next.js 14 起已弃用,改用严格的 remotePatterns,以保护你的应用免受恶意用户攻击。只有当你拥有该域名下提供的所有内容时,才使用 domains。

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

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

下面是 next.config.js 文件中 domains 属性的示例:

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

Loader 配置#

如果你想使用云服务商来优化图片,而不是使用 Next.js 内置的图片优化 API,可以在 next.config.js 文件中配置 loader 和 path 前缀。这使你可以为 Image 的 src 使用相对 URL,并自动为你的服务商生成正确的绝对 URL。

next.config.js
module.exports = {
  images: {
    loader: 'imgix',
    path: 'https://example.com/myaccount/',
  },
}

自定义内置图片路径#

使用默认 loader 时,path 设置 next/legacy/image 用于优化图片的 URL。path 的默认值为 /_next/image。

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

使用上面的示例时,next/legacy/image 会渲染出类似 /my-prefix/_next/image?url=...&w=...&q=... 的 src 值。

path 不会改变 Next.js 提供内置图片优化服务的位置。服务器始终在 /_next/image 提供该服务,如果设置了 basePath,则以其为前缀。Next.js 不会将 basePath 添加到自定义的 path 中。当你更改 path 时,位于 Next.js 前面的组件(如反向代理或 CDN)必须将该路径的请求以相同的查询字符串路由到 /_next/image,如果设置了 basePath,则路由到 <basePath>/_next/image。否则这些请求将返回 404。

对于 内置 loader(如 imgix、cloudinary 或 akamai),path 则是服务商的基本 URL,且为必填项。

内置 Loader#

以下是内置的图片优化云服务商:

  • 默认:与 next dev、next start 或自定义服务器自动配合工作
  • Vercel: 在 Vercel 上部署时自动工作,无需配置。了解更多
  • Imgix: loader: 'imgix'
  • Cloudinary: loader: 'cloudinary'
  • Akamai: loader: 'akamai'
  • 自定义:loader: 'custom',通过在 next/legacy/image 组件上实现 loader 属性来使用自定义云服务商

如果需要其他服务商,可以将 loader 属性与 next/legacy/image 一起使用。

使用 output: 'export' 时无法在构建时优化图片,只能按需优化。要将 next/legacy/image 与 output: 'export' 一起使用,需要使用不同于默认的 loader。在讨论中阅读更多内容。

高级#

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

设备尺寸#

如果你知道用户的预期设备宽度,可以使用 next.config.js 中的 deviceSizes 属性指定设备宽度断点列表。当 next/legacy/image 组件使用 layout="responsive" 或 layout="fill" 时,会使用这些宽度,以确保为用户的设备提供正确的图片。

如果未提供配置,则使用下面的默认值。

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

图片尺寸#

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

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

如果未提供配置,则使用下面的默认值。

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

可接受的格式#

默认的图片优化 API 会通过请求的 Accept 头自动检测浏览器支持的图片格式,以确定最佳的输出格式。

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

如果未提供配置,则使用下面的默认值。

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

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

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

你还可以同时启用 AVIF 和 WebP 两种格式。对于支持 AVIF 的浏览器,将优先使用 AVIF,WebP 作为回退:

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

小知识:

  • 对于大多数用例,我们仍然推荐使用 WebP。
  • AVIF 的编码时间通常比 WebP 长 50%,但压缩后的体积比 WebP 小 20%。这意味着首次请求图片时通常会较慢,而后续被缓存的请求会更快。
  • 使用多种格式时,Next.js 会分别缓存每种格式。与使用单一格式相比,这意味着更高的存储需求,因为会同时存储 AVIF 和 WebP 版本的图片以支持不同的浏览器。
  • 如果你在 Next.js 前面使用代理/CDN 进行自托管,必须配置代理以转发 Accept 头。

缓存行为#

以下描述默认 loader 的缓存算法。对于其他所有 loader,请参考你的云服务商文档。

图片会在请求时动态优化,并存储在 <distDir>/cache/images 目录中。优化后的图片文件将用于后续请求,直到过期。当请求匹配到已缓存但已过期的文件时,会立即提供过期的图片(stale)。然后在后台再次优化图片(也称为重新验证),并以新的过期日期保存到缓存中。

可以通过读取 x-nextjs-cache(部署在 Vercel 上时为 x-vercel-cache)响应头的值来确定图片的缓存状态。可能的值如下:

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

过期时间(更确切地说是最大年龄 Max Age)由 minimumCacheTTL 配置或上游图片的 Cache-Control 头定义,取两者中较大者。具体而言,使用 Cache-Control 头的 max-age 值。如果同时找到 s-maxage 和 max-age,则优先使用 s-maxage。max-age 也会传递给任何下游客户端,包括 CDN 和浏览器。

  • 当上游图片不包含 Cache-Control 头或该值很低时,你可以配置 minimumCacheTTL 来延长缓存时长。
  • 你可以配置 deviceSizes 和 imageSizes,以减少可能生成的图片总数。
  • 你可以配置 formats,禁用多种格式,改用单一图片格式。

最小缓存 TTL#

你可以为缓存的优化图片配置以秒为单位的生存时间(Time to Live,TTL)。在许多情况下,最好使用静态图片导入,它会自动对文件内容进行哈希,并使用长期有效的 immutable Cache-Control 头缓存图片。

如果未提供配置,则使用下面的默认值。

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

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

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

优化图片的过期时间(更确切地说是最大年龄 Max Age)由 minimumCacheTTL 或上游图片的 Cache-Control 头定义,取两者中较大者。

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

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

禁用静态导入#

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

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

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

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

允许危险的 SVG#

默认 loader 不会优化 SVG 图片,原因如下。首先,SVG 是矢量格式,意味着它可以无损调整大小。其次,SVG 具有许多与 HTML/CSS 相同的功能,如果没有适当的内容安全策略(Content Security Policy,CSP)头,可能会导致漏洞。

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

不过,如果你需要使用默认的图片优化 API 提供 SVG 图片,可以在 next.config.js 中设置 dangerouslyAllowSVG:

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

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

contentDispositionType#

默认 loader 将 Content-Disposition 头设置为 attachment,以提供更强的保护,因为该 API 可以提供任意远程图片。

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

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

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

动画图片#

默认 loader 会自动跳过动画图片的图片优化,并按原样提供图片。

对动画文件的自动检测是尽力而为的,支持 GIF、APNG 和 WebP。如果你想对某张动画图片明确跳过图片优化,请使用 unoptimized 属性。

版本历史#

版本变更
v16.0.0next/legacy/image 已弃用,并将在 Next.js 的未来版本中移除。请改用 next/image。
v13.0.0next/image 重命名为 next/legacy/image
Next.js 中文网