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 时,对于源图片还需考虑以下事项:
- 当 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 | 行为 | srcSet | sizes | 是否有包装器和尺寸调整器 |
|---|---|---|---|---|
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 的示例:
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 属性:
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 元素的示例
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 组件的示例
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)。
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。请改用 设备尺寸 作为替代。ref。请改用onLoadingComplete。decoding。它始终为"async"。
配置项#
远程模式#
为了保护你的应用免受恶意用户攻击,使用外部图片时必须进行配置。这确保只有来自你账户的外部图片才能通过 Next.js 图片优化 API 提供。这些外部图片可以在 next.config.js 文件中通过 remotePatterns 属性配置,如下所示:
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 中使用通配符模式的示例:
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 的示例:
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 属性的示例:
module.exports = {
images: {
domains: ['assets.acme.com'],
},
}Loader 配置#
如果你想使用云服务商来优化图片,而不是使用 Next.js 内置的图片优化 API,可以在 next.config.js 文件中配置 loader 和 path 前缀。这使你可以为 Image 的 src 使用相对 URL,并自动为你的服务商生成正确的绝对 URL。
module.exports = {
images: {
loader: 'imgix',
path: 'https://example.com/myaccount/',
},
}自定义内置图片路径#
使用默认 loader 时,path 设置 next/legacy/image 用于优化图片的 URL。path 的默认值为 /_next/image。
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" 时,会使用这些宽度,以确保为用户的设备提供正确的图片。
如果未提供配置,则使用下面的默认值。
module.exports = {
images: {
deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
},
}图片尺寸#
你可以在 next.config.js 文件中使用 images.imageSizes 属性指定图片宽度列表。这些宽度会与设备尺寸数组连接,形成用于生成图片 srcset 的完整尺寸数组。
之所以有两个独立的列表,是因为 imageSizes 仅用于提供 sizes 属性的图片,这表示图片宽度小于屏幕全宽。因此,imageSizes 中的尺寸都应小于 deviceSizes 中的最小尺寸。
如果未提供配置,则使用下面的默认值。
module.exports = {
images: {
imageSizes: [32, 48, 64, 96, 128, 256, 384],
},
}可接受的格式#
默认的图片优化 API 会通过请求的 Accept 头自动检测浏览器支持的图片格式,以确定最佳的输出格式。
如果 Accept 头匹配了多个配置的格式,则使用数组中第一个匹配的格式。因此,数组顺序很重要。如果没有匹配项(或源图片是动画图片),图片优化 API 将回退到原始图片的格式。
如果未提供配置,则使用下面的默认值。
module.exports = {
images: {
formats: ['image/webp'],
},
}你可以启用 AVIF 支持,如果浏览器不支持 AVIF,它将回退到 src 图片的格式:
module.exports = {
images: {
formats: ['image/avif'],
},
}你还可以同时启用 AVIF 和 WebP 两种格式。对于支持 AVIF 的浏览器,将优先使用 AVIF,WebP 作为回退:
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 头缓存图片。
如果未提供配置,则使用下面的默认值。
module.exports = {
images: {
minimumCacheTTL: 14400, // 4 小时
},
}你可以增加 TTL 以减少重新验证的次数,并可能降低成本:
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 中禁用静态图片导入:
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:
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,以允许浏览器在直接访问时渲染图片,而不下载它。
module.exports = {
images: {
contentDispositionType: 'inline',
},
}动画图片#
默认 loader 会自动跳过动画图片的图片优化,并按原样提供图片。
对动画文件的自动检测是尽力而为的,支持 GIF、APNG 和 WebP。如果你想对某张动画图片明确跳过图片优化,请使用 unoptimized 属性。
版本历史#
| 版本 | 变更 |
|---|---|
v16.0.0 | next/legacy/image 已弃用,并将在 Next.js 的未来版本中移除。请改用 next/image。 |
v13.0.0 | next/image 重命名为 next/legacy/image |