图片优化

示例

图片组件

根据 Web Almanac 的数据，图片在典型网站的页面权重中占很大比例，并且对网站的 LCP 性能有显著影响。

Next.js 的 Image 组件扩展了 HTML <img> 元素，提供自动图片优化功能：

尺寸优化： 自动为每个设备提供正确尺寸的图片，使用 WebP 和 AVIF 等现代图片格式。
视觉稳定性： 图片加载时自动防止布局偏移 (CLS)。
更快页面加载： 图片仅在进入视口时通过原生浏览器懒加载加载，可选模糊占位图。
资源灵活性： 按需调整图片尺寸，即使是远程服务器存储的图片。

🎥 观看视频： 了解更多关于如何使用 next/image → YouTube (9分钟)。

使用方法

import Image from 'next/image'

然后您可以定义图片的 src（本地或远程均可）。

本地图片

要使用本地图片，请 import 您的 .jpg、.png 或 .webp 图片文件。

Next.js 会根据导入的文件自动确定图片的 width 和 height。这些值用于防止图片加载时的累积布局偏移 (CLS)。

pages/index.js

import Image from 'next/image'
import profilePic from '../public/me.png'

export default function Page() {
  return (
    <Image
      src={profilePic}
      alt="作者照片"
      // width={500} 自动提供
      // height={500} 自动提供
      // blurDataURL="data:..." 自动提供
      // placeholder="blur" // 加载时可选的模糊效果
    />
  )
}

警告： 不支持动态 await import() 或 require()。import 必须是静态的，以便在构建时进行分析。

远程图片

要使用远程图片，src 属性应为 URL 字符串。

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

width 和 height 属性用于推断图片的正确宽高比，并避免图片加载时的布局偏移。width 和 height 并不决定图片文件的渲染尺寸。了解更多关于图片尺寸。

app/page.js

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="https://s3.amazonaws.com/my-bucket/profile.png"
      alt="作者照片"
      width={500}
      height={500}
    />
  )
}

为了安全地允许优化图片，请在 next.config.js 中定义支持的 URL 模式列表。尽可能具体以防止恶意使用。例如，以下配置仅允许来自特定 AWS S3 存储桶的图片：

next.config.js

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 's3.amazonaws.com',
        port: '',
        pathname: '/my-bucket/**',
      },
    ],
  },
}

了解更多关于 remotePatterns 配置。如果想为图片 src 使用相对 URL，请使用 loader。

域名

有时您可能希望优化远程图片，但仍使用内置的 Next.js 图片优化 API。为此，将 loader 保留为默认设置，并为 Image src 属性输入绝对 URL。

为了保护您的应用程序免受恶意用户攻击，您必须定义要与 next/image 组件一起使用的远程主机名列表。

了解更多关于 remotePatterns 配置。

加载器

请注意，在前面的示例中，为本地图片提供了部分 URL ("/me.png")。这得益于加载器架构。

加载器是一个为您的图片生成 URL 的函数。它修改提供的 src，并生成多个 URL 以请求不同尺寸的图片。这些多个 URL 用于自动生成 srcset，以便为访问者提供适合其视口大小的图片。

Next.js 应用程序的默认加载器使用内置的图片优化 API，该 API 优化来自网络任何位置的图片，然后直接从 Next.js 网络服务器提供。如果您希望直接从 CDN 或图片服务器提供图片，可以用几行 JavaScript 编写自己的加载器函数。

您可以通过 loader 属性为每个图片定义加载器，或通过 loaderFile 配置在应用程序级别定义。

优先级

您应该为每个页面的最大内容绘制 (LCP) 元素图片添加 priority 属性。这样做允许 Next.js 特别优先加载该图片（例如通过预加载标签或优先级提示），从而显著提升 LCP。

LCP 元素通常是页面视口中可见的最大图片或文本块。当您运行 next dev 时，如果 LCP 元素是没有 priority 属性的 <Image>，您会看到控制台警告。

一旦确定了 LCP 图片，您可以像这样添加属性：

app/page.js

import Image from 'next/image'

export default function Home() {
  return (
    <>
      <h1>我的主页</h1>
      <Image
        src="/me.png"
        alt="作者照片"
        width={500}
        height={500}
        priority
      />
      <p>欢迎来到我的主页！</p>
    </>
  )
}

有关优先级的更多信息，请参阅 next/image 组件文档。

图片尺寸

图片最常见的性能损害方式之一是通过_布局偏移_，即图片在加载时将页面上的其他元素推开。这个性能问题对用户来说非常烦人，以至于它有自己的核心 Web 指标，称为累积布局偏移 (CLS)。避免基于图片的布局偏移的方法是始终为图片指定尺寸。这允许浏览器在图片加载前预留足够的空间。

因为 next/image 旨在保证良好的性能结果，所以不能以会导致布局偏移的方式使用，并且必须通过以下三种方式之一指定尺寸：

自动，使用静态导入
显式，通过包含 width 和 height 属性
隐式，通过使用 fill 使图片扩展以填充其父元素。

如果我不知道图片的尺寸怎么办？

如果您从不知道图片尺寸的来源访问图片，可以采取以下措施：

使用 fill

fill 属性允许您的图片由其父元素调整大小。考虑使用 CSS 为图片的父元素在页面上留出空间，并使用 sizes 属性匹配任何媒体查询断点。您还可以将 object-fit 与 fill、contain 或 cover 一起使用，以及 object-position 来定义图片应如何占据该空间。

标准化您的图片

如果您从您控制的来源提供图片，考虑修改您的图片管道以将图片标准化为特定尺寸。

修改您的 API 调用

如果您的应用程序通过 API 调用（例如 CMS）检索图片 URL，您可以修改 API 调用以返回图片尺寸以及 URL。

如果以上建议的方法都不适用于调整图片尺寸，next/image 组件设计为可以与标准 <img> 元素在页面上良好配合使用。

样式

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

使用 className 或 style，而不是 styled-jsx。
- 在大多数情况下，我们建议使用 className 属性。这可以是导入的 CSS 模块、全局样式表等。
- 您也可以使用 style 属性分配内联样式。
- 不能使用 styled-jsx，因为它的作用域限定在当前组件（除非将样式标记为 global）。
使用 fill 时，父元素必须具有 position: relative
- 这是在该布局模式下正确渲染图片元素所必需的。
使用 fill 时，父元素必须具有 display: block
- 这是 <div> 元素的默认值，但其他情况下应明确指定。

示例

响应式

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Responsive() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column' }}>
      <Image
        alt="山脉"
        // 导入图片将
        // 自动设置宽度和高度
        src={mountains}
        sizes="100vw"
        // 使图片显示为全宽
        style={{
          width: '100%',
          height: 'auto',
        }}
      />
    </div>
  )
}

填充容器

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', height: '400px' }}>
        <Image
          alt="山脉"
          src={mountains}
          fill
          sizes="(min-width: 808px) 50vw, 100vw"
          style={{
            objectFit: 'cover', // cover, contain, none
          }}
        />
      </div>
      {/* 网格中的更多图片... */}
    </div>
  )
}

背景图片

import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Background() {
  return (
    <Image
      alt="山脉"
      src={mountains}
      placeholder="blur"
      quality={100}
      fill
      sizes="100vw"
      style={{
        objectFit: 'cover',
      }}
    />
  )
}

有关 Image 组件与各种样式一起使用的示例，请参阅 Image 组件演示。

其他属性

查看 next/image 组件的所有可用属性。

配置

next/image 组件和 Next.js 图片优化 API 可以在 next.config.js 文件中配置。这些配置允许您启用远程图片、定义自定义图片断点、更改缓存行为等。

阅读完整的图片配置文档以获取更多信息。

On this page