圖片優化

範例

圖片元件

根據 Web Almanac 的數據，圖片佔了典型網站頁面重量的很大一部分，並對網站的 LCP 效能有顯著影響。

Next.js 的 Image 元件擴展了 HTML <img> 元素，提供自動圖片優化的功能：

尺寸優化： 自動為每種裝置提供正確尺寸的圖片，使用現代圖片格式如 WebP 和 AVIF。
視覺穩定性： 自動防止圖片載入時的版面偏移 (layout shift)。
更快的頁面載入： 圖片僅在進入視窗時載入，使用瀏覽器原生的懶加載，並可選擇模糊預覽佔位圖。
資源靈活性： 按需調整圖片尺寸，即使是遠端伺服器上的圖片。

🎥 觀看： 了解更多如何使用 next/image → YouTube (9 分鐘)。

使用方法

import Image from 'next/image'

然後您可以定義圖片的 src（本地或遠端）。

本地圖片

要使用本地圖片，請 import 您的 .jpg、.png 或 .webp 圖片檔案。

Next.js 會根據導入的檔案自動判斷圖片的 width 和 height。這些值用於防止圖片載入時的累積版面偏移 (Cumulative Layout Shift)。

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 元件文件中查看更多關於優先級的資訊。

圖片尺寸

圖片最常見的效能問題之一是_版面偏移_，即圖片載入時將頁面上的其他元素推開。這個效能問題對用戶來說非常煩人，以至於它有自己的核心網頁指標，稱為累積版面偏移 (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 Component Demo。

其他屬性

查看 next/image 元件所有可用的屬性。

配置

next/image 元件和 Next.js 圖片優化 API 可以在 next.config.js 文件中配置。這些配置允許您啟用遠端圖片、定義自定義圖片斷點、更改緩存行為等。

閱讀完整的圖片配置文件以獲取更多資訊。

On this page