Menu

Image Optimization

示例

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

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

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

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

使用方法

import Image from 'next/image'

然后你可以定义图片的 src (本地或远程图片)。

本地图片

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

Next.js 将根据导入的文件自动确定图片的固有 width 和 height。这些值用于确定图片比例并防止图片加载时产生累积布局偏移。

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 必须是静态的，这样才能在构建时进行分析。

你可以在 next.config.js 文件中配置 localPatterns 来允许特定图片并阻止其他图片。

next.config.js
module.exports = {
  images: {
    localPatterns: [
      {
        pathname: '/assets/images/**',
        search: '',
      },
    ],
  },
}

远程图片

要使用远程图片，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。

Domains

有时你可能想要优化远程图片，但仍然使用内置的 Next.js 图片优化 API。要做到这一点，请将 loader 保持默认设置，并为 Image 组件的 src 属性输入一个绝对 URL。

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

了解更多关于 remotePatterns 配置。

Loaders

注意在前面的示例中，为本地图片提供了一个部分 URL ("/me.png")。这是因为 loader 架构使其成为可能。

loader 是一个生成图片 URL 的函数。它修改提供的 src，并生成多个 URL 以不同尺寸请求图片。这些多个 URL 用于自动生成 srcset，这样访问你网站的用户将得到适合其视口大小的图片。

Next.js 应用程序的默认 loader 使用内置的图片优化 API，它可以优化来自网络任何地方的图片，然后直接从 Next.js 网络服务器提供。如果你想直接从 CDN 或图片服务器提供图片，你可以用几行 JavaScript 编写自己的 loader 函数。

你可以通过 loader 属性为每个图片定义 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 组件文档中了解更多关于优先级的信息。

图片尺寸

图片最常见的性能问题之一是布局偏移，即图片在加载时推动页面上的其他元素。这个性能问题对用户来说非常烦人，以至于它有自己的核心网页指标，称为累积布局偏移。避免基于图片的布局偏移的方法是始终为图片设置尺寸。这允许浏览器在图片加载之前为其预留精确的空间。

由于 next/image 的设计目的是保证良好的性能结果，它不能以会导致布局偏移的方式使用，并且必须通过以下三种方式之一来设置尺寸：

  1. 使用静态导入自动设置
  2. 手动包含 width 和 height 属性来确定图片的宽高比
  3. 隐式地使用 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 Module、全局样式表等。
    • 你也可以使用 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 文件中配置。这些配置允许你启用远程图片、定义自定义图片断点、更改缓存行为等。

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