NNext.js 中文网 GitHub

Image

使用内置的 next/image 组件优化 Next.js 应用中的图片。

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 文档,因为该组件已重命名。

参考#

属性#

以下属性可用:

<div style={{ overflowX: 'auto', width: '100%' }}>

属性示例类型状态
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-

</div>

src#

图片的来源。可以是以下之一:

内部路径字符串。

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

绝对的外部 URL(必须使用 remotePatterns 配置)。

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

静态导入。

jsx
import profile from './profile.png'

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

小知识:出于安全原因,使用默认 loader 的图片优化 API 在获取 src 图片时不会转发请求头。 如果 src 图片需要身份验证,请考虑使用 unoptimized 属性来禁用图片优化。

alt#

alt 属性用于向屏幕阅读器和搜索引擎描述图片。当图片被禁用或加载图片时发生错误,它也是替代文本。

它应包含能够在不改变页面含义的情况下替代图片的文本。它并非用于补充图片,也不应重复图片上方或下方说明文字中已经提供的信息。

如果图片是纯装饰性的或不面向用户,则 alt 属性应为空字符串(alt="")。

了解更多关于图片无障碍指南的信息。

width 和 height#

width 和 height 属性表示图片的固有尺寸(以像素为单位)。该属性用于推断正确的宽高比,浏览器据此为图片预留空间,避免加载过程中发生布局偏移。它不决定图片的渲染尺寸,渲染尺寸由 CSS 控制。

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

你必须同时设置 width 和 height 属性,除非:

如果不知道高度和宽度,我们建议使用 fill 属性。

fill#

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

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

定位:

  • 父元素必须指定 position: "relative"、"fixed"、"absolute"。
  • 默认情况下,<img> 元素使用 position: "absolute"。

对象适配(Object Fit):

如果未对图片应用任何样式,图片将拉伸以适应容器。你可以使用 objectFit 来控制裁剪和缩放。

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

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

loader#

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

js
'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="Picture of the author"
      width={500}
      height={500}
    />
  )
}

小知识:使用像 onLoad 这样接受函数的属性,需要使用 Client Components 来序列化所提供的函数。

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

next.config.js 中的大多数 images 选项用于配置内置的图片优化 API,不适用于由自定义 loader 提供服务的图片。这包括与安全相关的选项 images.remotePatterns、images.localPatterns、images.dangerouslyAllowLocalIP、images.dangerouslyAllowSVG、images.contentDispositionType 和 images.contentSecurityPolicy。实现类似保护取决于 loader 自身。

sizes#

定义图片在不同断点的尺寸。浏览器使用它从生成的 srcset 中选择最合适的尺寸。

jsx
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 时,对于具有 width 的图片:Next.js 会生成有限的 srcset(例如 1x、2x),适用于固定尺寸的图片。
  • 不带 sizes 时,对于 fill 图片:Next.js 仅从 deviceSizes 生成 srcset,就好像图片横跨整个视口。
  • 带 sizes 时:Next.js 会生成完整的 srcset(例如 640w、750w 等),针对响应式布局优化。

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

quality#

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

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

如果你在 next.config.js 中配置了 qualities,超出该列表的值会被强制转换为最接近的允许值。例如,使用 qualities: [50, 75, 100] 时,quality 为 80 将以 75 提供。开发模式下会记录警告,以便你将该值添加到允许列表。

小知识:如果原图质量已经很低,设置较高的质量值只会增加文件大小,而不会改善外观。

style#

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

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

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

小知识:如果你使用 style 属性设置自定义宽度,请务必同时设置 height: 'auto' 以保持图片的宽高比。

preload#

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

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

何时使用:

当你希望浏览器在 <body> 中发现其 <img> 元素之前就开始加载图片时,可对已知的最大内容绘制(LCP)图片(例如首屏主图)使用 preload。

何时不使用:

  • 当有多张图片可能根据视口不同而被视为最大内容绘制(LCP)元素时。
  • 使用了 loading 属性时。
  • 使用了 fetchPriority 属性时。

大多数情况下,对首屏图片使用 loading="eager" 以禁用懒加载。添加 fetchPriority="high" 可让浏览器优先处理该请求。fetchPriority 本身不会禁用懒加载。

React 还可能在服务端渲染期间自动预加载急切加载的图片。了解更多关于 React 的图片预加载行为。

priority#

从 Next.js 16 开始,priority 属性已弃用。使用 preload 来保持相同的预加载行为,或如果只需要禁用懒加载,则使用 loading="eager"。

loading#

控制图片何时开始加载。

jsx
// 默认为懒加载
<Image loading="lazy" />
  • lazy:延迟加载图片,直到其接近视口到计算出的距离时才加载。
  • eager:立即加载图片,无论其在页面中的位置如何。

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

了解更多关于 loading 属性的信息。

placeholder#

指定图片加载时使用的占位符,以提升感知加载性能。

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

示例:

了解更多关于 placeholder 属性的信息。

blurDataURL#

在图片成功加载之前用作占位图的 Data URL。可以自动设置,或与 placeholder="blur" 属性一起使用。

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

图片会被自动放大并模糊处理,因此建议使用非常小的图片(10px 或更小)。

自动

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

手动设置

如果图片是动态的或远程的,你必须自己提供 blurDataURL。要生成它,你可以使用:

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

示例:

onLoad#

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

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

回调函数将接收一个参数,即事件对象,其 target 指向底层的 <img> 元素。

小知识:使用像 onLoad 这样接受函数的属性,需要使用 Client Components 来序列化所提供的函数。

onError#

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

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

小知识:使用像 onError 这样接受函数的属性,需要使用 Client Components 来序列化所提供的函数。

unoptimized#

一个布尔值,指示图片是否应跳过图片优化 API 而按原样提供。这对那些无法从优化中受益的图片很有用,例如小图片(小于 1KB)、矢量图片(SVG)或动画图片(GIF)。

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

next.config.js 中的大多数 images 选项用于配置内置的图片优化 API,不适用于未优化的图片。这包括 contentDispositionType 和 contentSecurityPolicy。

overrideSrc#

当向 <Image> 组件提供 src 属性时,会为生成的 <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 属性覆盖它。

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

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#

给浏览器的一个提示,指示在呈现其他内容更新之前是否应等待图片解码完成。

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

了解更多关于 decoding 属性的信息。

其他属性#

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

已弃用的属性#

onLoadingComplete#

警告:在 Next.js 14 中已弃用,请改用 onLoad。

在图片完全加载且 placeholder 被移除后调用的回调函数。

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

jsx
'use client'

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

小知识:使用像 onLoadingComplete 这样接受函数的属性,需要使用 Client Components 来序列化所提供的函数。

配置项#

你可以在 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。

请注意,任何返回重定向的允许的 remotePatterns 都会跟随远程图片服务器的重定向,而不会在重定向位置再次校验 remotePatterns。你可以通过配置 maximumRedirects 来减少或禁用重定向。

loaderFile#

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

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

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

my/image/loader.js
'use client'

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

示例:

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

path#

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

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

使用上面的示例,next/image 会渲染出诸如 /my-prefix/_next/image?url=...&w=...&q=... 这样的 src 值。

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

deviceSizes#

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

如果未提供配置,则使用以下默认值:

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 属性的图片,这表示该图片的宽度小于屏幕的完整宽度。因此,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 属性与该数组中的值不匹配,则使用最接近的允许值。

如果直接访问 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'],
  },
}

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

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

小知识:

  • 对于大多数用例,我们仍建议使用 WebP。
  • AVIF 的编码时间通常要长 50%,但相比 WebP 压缩后体积小 20%。这意味着首次请求图片时通常较慢,但后续被缓存的请求会更快。
  • 使用多种格式时,Next.js 会分别缓存每种格式。与仅使用单一格式相比,这会增加存储需求,因为会同时存储 AVIF 和 WebP 版本的图片以支持不同的浏览器。
  • 如果你自托管时在 Next.js 前面使用了代理(Proxy)或 CDN,则必须配置代理转发 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 属性或删除缓存文件 <distDir>/cache/images。

disableStaticImages#

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

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

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

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

maximumRedirects#

默认的图片优化 loader 在获取远程图片时最多会跟随 3 次 HTTP 重定向。

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

为方便起见,这些重定向无需满足 remotePatterns。

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

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

maximumDiskCacheSize#

默认的图片优化 loader 会将优化后的图片写入磁盘,以便后续请求可以更快地从磁盘缓存中提供。

你可以配置磁盘缓存的最大大小(以字节为单位),例如 500 MB:

next.config.js
module.exports = {
  images: {
    maximumDiskCacheSize: 500_000_000,
  },
}

你也可以将该值设置为 0 来完全禁用磁盘缓存。

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

如果未配置任何值,默认行为是在启动时检查一次当前可用的磁盘空间,并使用其中的 50%。

当磁盘缓存超过配置的大小时,将删除最近最少使用的优化图片,直到缓存重新低于限制。

或者,你可以使用 cacheHandler 实现自己的缓存处理器,它将忽略 maximumDiskCacheSize 配置。

maximumResponseBody#

默认的图片优化 loader 会获取大小不超过 50 MB 的源图片。

next.config.js
module.exports = {
  images: {
    maximumResponseBody: 50_000_000,
  },
}

如果你知道所有源图片都很小,可以通过将其减小到更小的值(例如 5 MB)来保护内存受限的服务器。

next.config.js
module.exports = {
  images: {
    maximumResponseBody: 5_000_000,
  },
}

dangerouslyAllowLocalIP#

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

默认情况下,该值为 false。

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

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

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

当在具有水平分割 DNS 的 VPC 中托管 Next.js 并且收到 400 Bad Request 状态时,可能需要这样做。只有在了解 SSRF 风险后才启用。

dangerouslyAllowSVG#

Next.js 从不对 SVG 图片进行缩放或压缩。SVG 是一种矢量格式,这意味着浏览器可以在不损失质量的情况下缩放图片。无需服务端栅格化。

SVG 具有许多与 HTML/CSS 相同的功能,包括支持内联 <script> 标签。使用默认 loader 的图片优化 API 通过与你的应用程序相同的域名提供图片。当不受信任的 SVG 与你的应用程序同源提供时,如果没有适当的 contentDispositionType 和内容安全策略(CSP)头,可能会引入漏洞。

我们建议不要使用 dangerouslyAllowSVG,而是在 src 属性为 SVG 时使用 unoptimized 属性。当 src 以 ".svg" 结尾时,会自动执行此操作。

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

这会跳过图片优化 API,直接从源提供 SVG。

使用 unoptimized 时,Next.js 不会通过你的域名代理远程不受信任的图片。由于同源策略,这降低了 XSS 风险。你不得从自己的域名提供不受信任的 SVG。

如果你无法使用 unoptimized 属性且了解风险,可以通过 dangerouslyAllowSVG: true 在图片优化 API 中启用 SVG 透传。SVG 将不经修改地通过你的域名代理。

使用 dangerouslyAllowSVG 时,强烈建议保留默认的 contentDispositionType: 'attachment' 以强制浏览器下载图片,同时保留默认的 contentSecurityPolicy 以防止图片中嵌入的脚本执行。

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

dangerouslyAllowSVG 的默认值为 false。

contentDispositionType#

contentDispositionType 允许你配置 Content-Disposition 头。

默认值为 attachment,它会在直接访问时强制浏览器下载图片。当 dangerouslyAllowSVG 为 true 时,这一点尤其重要,因为该 API 可以提供任意远程图片。

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

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

此选项仅适用于图片优化 API,不适用于 unoptimized 图片或使用自定义 loader 的图片。

contentSecurityPolicy#

contentSecurityPolicy 允许你为图片配置 Content-Security-Policy 头。

默认值可防止使用 dangerouslyAllowSVG 提供的 SVG 文件在没有 contentDispositionType: 'attachment' 的情况下被直接访问时执行脚本或包含 iframe。

next.config.js
module.exports = {
  images: {
    contentSecurityPolicy: "script-src 'none'; frame-src 'none'; sandbox;", // 默认值
  },
}

你可以配置更严格的策略,例如将图片、样式和字体等其他资源也限制在应用程序的来源内:

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

此选项仅适用于图片优化 API,不适用于 unoptimized 图片或使用自定义 loader 的图片。

已弃用的配置项#

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> 元素的属性,并将这些属性改为传递给另一个组件、样式、画布等。

jsx
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 组件使用浏览器原生的懒加载,对于 Safari 15.4 之前的旧浏览器,可能会回退到急切加载。使用模糊占位符时,Safari 12 之前的旧浏览器会回退到空占位符。当使用 width/height 为 auto 的样式时,在 Safari 15 之前不保留宽高比的旧浏览器上可能会导致布局偏移。有关更多详细信息,请参阅这个 MDN 视频。

示例#

图片样式#

为 Image 组件设置样式与为普通 <img> 元素设置样式类似,但有一些准则需要牢记:

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

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

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

你还可以使用 style 属性来指定内联样式。

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

使用 fill 时,父元素必须设置定位,即 position: relative、fixed 或 absolute。图片本身使用 position: absolute,因此其尺寸相对于最近的已定位祖先元素。

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

你不能使用 styled-jsx,因为它的作用域限定在当前组件内(除非你将样式标记为 global)。

使用静态导出的响应式图片#

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

jsx
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 或远程 URL,你必须提供宽度和高度属性,以便 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 属性并将 objectFit 属性设置为 cover。这将使图片填满其父容器的整个宽度。

jsx
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 属性使图片覆盖整个屏幕区域:

jsx
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 属性。

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
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} />
    </>
  )
}
components/theme-image.js
import styles from './theme-image.module.css'
import Image from 'next/image'

const ThemeImage = (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"。

试试看:

艺术指导#

如果你想为移动端和桌面端显示不同的图片(有时称为 Art Direction(艺术指导)),可以向 getImageProps() 提供不同的 src、width、height 和 quality 属性。

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.1.7新增 maximumDiskCacheSize 配置。
v16.1.2新增 maximumResponseBody 配置。
v16.0.0qualities 默认配置改为 [75],新增 preload 属性,priority 属性已弃用,新增 dangerouslyAllowLocalIP 配置,新增 maximumRedirects 配置。
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.0onLoadingComplete 属性和 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。可使用 codemod 安全自动地重命名你的导入。移除了 <span> 包装。layout、objectFit、objectPosition、lazyBoundary、lazyRoot 属性已移除。alt 为必填。onLoadingComplete 接收对 img 元素的引用。移除了内置 loader 配置。
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。
Next.js 中文网