<Image>

此 API 參考將幫助您了解如何使用圖片元件提供的 屬性 (props) 和 配置選項。關於功能和用法，請參閱 圖片元件 頁面。

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="作者的照片"
    />
  )
}

屬性

以下是圖片元件可用的屬性摘要：

必填屬性

圖片元件需要以下屬性：src、width、height 和 alt。

import Image from 'next/image'

export default function Page() {
  return (
    <div>
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="作者的照片"
      />
    </div>
  )
}

src

必須是以下之一：

• 靜態匯入 的圖片檔案
• 路徑字串。可以是絕對外部 URL 或內部路徑，具體取決於 loader 屬性。

使用外部 URL 時，必須將其新增到 next.config.js 中的 remotePatterns。

width

width 屬性代表 渲染 寬度（以像素為單位），因此會影響圖片的顯示大小。

必填，除非是 靜態匯入的圖片 或使用 fill 屬性 的圖片。

height

height 屬性代表 渲染 高度（以像素為單位），因此會影響圖片的顯示大小。

必填，除非是 靜態匯入的圖片 或使用 fill 屬性 的圖片。

alt

alt 屬性用於為螢幕閱讀器和搜尋引擎描述圖片。如果圖片被禁用或載入時發生錯誤，它也是替代文字。

應包含可以替代圖片 而不改變頁面含義 的文字。它不是用來補充圖片的，也不應重複圖片上方或下方標題中已提供的資訊。

如果圖片是 純裝飾性 或 不面向使用者，alt 屬性應為空字串 (alt="")。

了解更多

可選屬性

<Image /> 元件接受許多超出必填屬性的附加屬性。本節介紹圖片元件最常用的屬性。更多罕見屬性的詳細資訊請參閱 進階屬性 部分。

loader

用於解析圖片 URL 的自訂函式。

loader 是一個函式，根據以下參數返回圖片的 URL 字串：

• src
• width
• quality

以下是使用自訂 loader 的範例：

'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="作者的照片"
      width={500}
      height={500}
    />
  )
}

須知：使用像 loader 這樣接受函式的屬性時，需要使用 客戶端元件 (Client Components) 來序列化提供的函式。

或者，您可以在 next.config.js 中使用 loaderFile 配置來配置應用程式中所有 next/image 的實例，而無需傳遞屬性。

fill

fill={true} // {true} | {false}

一個布林值，使圖片填滿父元素，這在 width 和 height 未知時非常有用。

父元素 必須 設定 position: "relative"、position: "fixed" 或 position: "absolute" 樣式。

預設情況下，img 元素會自動被賦予 position: "absolute" 樣式。

如果沒有對圖片應用任何樣式，圖片將拉伸以適應容器。您可能更喜歡設定 object-fit: "contain" 來保持圖片的原始比例。

或者，object-fit: "cover" 會使圖片填滿整個容器並被裁剪以保持比例。為了看起來正確，父元素應設定 overflow: "hidden" 樣式。

更多資訊請參閱：

• position
• object-fit
• object-position

sizes

一個類似媒體查詢的字串，提供有關圖片在不同斷點下寬度的資訊。sizes 的值將極大地影響使用 fill 或 設定為響應式大小 的圖片的效能。

sizes 屬性有兩個與圖片效能相關的重要用途：

1. 首先，瀏覽器使用 sizes 的值來決定從 next/image 自動生成的 srcset 中下載哪個大小的圖片。當瀏覽器選擇時，它還不知道圖片在頁面上的大小，因此它會選擇與視窗大小相同或更大的圖片。sizes 屬性允許您告訴瀏覽器圖片實際上會比全螢幕小。如果在使用 fill 屬性的圖片中未指定 sizes 值，則預設使用 100vw（全螢幕寬度）。
2. 其次，sizes 屬性會改變自動生成的 srcset 值的行為。如果沒有 sizes 值，則生成一個小的 srcset，適合固定大小的圖片（1x/2x 等）。如果定義了 sizes，則生成一個大的 srcset，適合響應式圖片（640w/750w 等）。如果 sizes 屬性包含像 50vw 這樣的值，代表視窗寬度的百分比，則 srcset 會被修剪，不包含任何可能永遠不需要的小值。

例如，如果您知道您的樣式會導致圖片在行動裝置上全寬顯示，在平板電腦上為 2 欄佈局，在桌面上為 3 欄佈局，則應包含如下所示的 sizes 屬性：

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 可能會對效能指標產生顯著影響。如果沒有 33vw 的 sizes，從伺服器選擇的圖片寬度將是實際需要的 3 倍。由於檔案大小與寬度的平方成正比，沒有 sizes 時，使用者將下載比實際需要大 9 倍的圖片。

了解更多關於 srcset 和 sizes：

• web.dev
• mdn

quality

quality={75} // {number 1-100}

優化圖片的品質，介於 1 和 100 之間的整數，其中 100 是最高品質，因此檔案大小也最大。預設為 75。

priority

priority={false} // {false} | {true}

當為 true 時，圖片將被視為高優先級並進行 預載 (preload)。對於使用 priority 的圖片，懶加載會自動禁用。

您應在檢測為 最大內容繪製 (LCP) 元素的任何圖片上使用 priority 屬性。對於不同的視窗大小，不同的圖片可能是 LCP 元素，因此可能需要多個優先級圖片。

僅當圖片在首屏可見時使用。預設為 false。

placeholder

placeholder = 'empty' // "empty" | "blur" | "data:image/..."

圖片載入時使用的佔位符。可能的值為 blur、empty 或 data:image/...。預設為 empty。

當為 blur 時，將使用 blurDataURL 屬性作為佔位符。如果 src 是 靜態匯入 的物件，且匯入的圖片為 .jpg、.png、.webp 或 .avif，則 blurDataURL 將自動填充，除非檢測到圖片是動畫。

對於動態圖片，您必須提供 blurDataURL 屬性。像 Plaiceholder 這樣的解決方案可以幫助生成 base64。

當為 data:image/... 時，Data URL 將在圖片載入時用作佔位符。

當為 empty 時，圖片載入時將沒有佔位符，只有空白空間。

試試看：

• 演示 blur 佔位符
• 演示使用 data URL placeholder 屬性的微光效果
• 演示使用 blurDataURL 屬性的顏色效果

進階屬性

在某些情況下，您可能需要更高級的用法。<Image /> 元件可選地接受以下進階屬性。

style

允許將 CSS 樣式傳遞給底層的圖片元素。

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
}

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

請記住，必填的 width 和 height 屬性可能會與您的樣式互動。如果您使用樣式修改圖片的寬度，則應將其高度樣式設為 auto 以保持其固有比例，否則圖片可能會變形。

onLoadingComplete

'use client'

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

一個回呼函式，在圖片完全載入且 佔位符 已移除後呼叫。

回呼函式將使用一個參數呼叫，即底層 <img> 元素的參考。

須知：使用像 onLoadingComplete 這樣接受函式的屬性時，需要使用 客戶端元件 (Client Components) 來序列化提供的函式。

onLoad

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

一個回呼函式，在圖片載入時呼叫。

載入事件可能在圖片佔位符被移除且圖片完全解碼之前發生。如果您想等待圖片完全載入，請改用 onLoadingComplete。

須知：使用像 onLoad 這樣接受函式的屬性時，需要使用 客戶端元件 (Client Components) 來序列化提供的函式。

onError

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

一個回呼函式，在圖片載入失敗時呼叫。

須知：使用像 onError 這樣接受函式的屬性時，需要使用 客戶端元件 (Client Components) 來序列化提供的函式。

loading

建議：此屬性僅適用於高級用例。將圖片切換為使用 eager 載入通常會 損害效能。我們建議改用 priority 屬性，它會急切地預載圖片。

loading = 'lazy' // {lazy} | {eager}

圖片的載入行為。預設為 lazy。

當為 lazy 時，延遲載入圖片，直到它到達與視窗的計算距離。

當為 eager 時，立即載入圖片。

了解更多關於 loading 屬性。

blurDataURL

一個 Data URL 用於在 src 圖片成功載入前作為佔位圖像。僅在與 placeholder="blur" 結合使用時生效。

必須是 base64 編碼的圖片。它會被放大並模糊化，因此建議使用非常小的圖片（10px 或更小）。包含較大的圖片作為佔位圖可能會影響應用程式效能。

試試看：

• 演示預設的 blurDataURL 屬性
• 演示使用 blurDataURL 屬性的色彩效果

你也可以 生成一個純色 Data URL 來匹配圖片。

unoptimized

unoptimized = {false} // {false} | {true}

當設為 true 時，原始圖片將以原樣提供，不會改變品質、大小或格式。預設為 false。

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。請改用 裝置尺寸 (Device Sizes)。
• decoding。它始終為 "async"。

配置選項

除了屬性外，你還可以在 next.config.js 中配置圖片組件。以下是可用的選項：

remotePatterns

為保護應用程式免受惡意用戶攻擊，使用外部圖片需要進行配置。這確保只有來自你帳戶的外部圖片可以通過 Next.js 圖片優化 API 提供。這些外部圖片可以在 next.config.js 文件中通過 remotePatterns 屬性進行配置，如下所示：

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'example.com',
        port: '',
        pathname: '/account123/**',
      },
    ],
  },
}

須知：上述範例將確保 next/image 的 src 屬性必須以 https://example.com/account123/ 開頭。任何其他協議、主機名、端口或不匹配的路徑將返回 400 Bad Request。

以下是 next.config.js 文件中 remotePatterns 屬性的另一個範例：

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
      },
    ],
  },
}

須知：上述範例將確保 next/image 的 src 屬性必須以 https://img1.example.com 或 https://me.avatar.example.com 或任意數量的子域名開頭。任何其他協議或不匹配的主機名將返回 400 Bad Request。

萬用字元模式可用於 pathname 和 hostname，並具有以下語法：

• * 匹配單一路徑段或子域名
• ** 匹配任意數量的路徑段（在末尾）或子域名（在開頭）

** 語法不能在模式的中間使用。

domains

警告：我們建議配置嚴格的 remotePatterns 而非 domains，以保護應用程式免受惡意用戶攻擊。僅在你擁有該域名下的所有內容時才使用 domains。

與 remotePatterns 類似，domains 配置可用於提供允許的外部圖片主機名列表。

然而，domains 配置不支持萬用字元模式匹配，且無法限制協議、端口或路徑名。

以下是 next.config.js 文件中 domains 屬性的範例：

module.exports = {
  images: {
    domains: ['assets.acme.com'],
  },
}

loaderFile

如果你想使用雲端供應商來優化圖片，而非使用 Next.js 內建的圖片優化 API，可以在 next.config.js 中配置 loaderFile，如下所示：

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

這必須指向相對於 Next.js 應用程式根目錄的文件。該文件必須導出一個返回字串的預設函數，例如：

'use client'

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

或者，你也可以使用 loader 屬性 來配置每個 next/image 實例。

範例：

• 自訂圖片載入器配置

須知：自訂圖片載入器文件（接受函數）需要使用 客戶端組件 (Client Components) 來序列化提供的函數。

進階

以下配置適用於進階使用場景，通常不需要。如果你選擇配置以下屬性，將覆蓋未來更新中 Next.js 預設的任何變更。

deviceSizes

如果你知道用戶的預期裝置寬度，可以在 next.config.js 中使用 deviceSizes 屬性指定裝置寬度斷點列表。當 next/image 組件使用 sizes 屬性時，這些寬度用於確保為用戶的裝置提供正確的圖片。

如果未提供配置，則使用以下預設值：

module.exports = {
  images: {
    deviceSizes: [640, 750, 828, 1080, 1200, 1920, 2048, 3840],
  },
}

imageSizes

你可以在 next.config.js 文件中使用 images.imageSizes 屬性指定圖片寬度列表。這些寬度與 裝置尺寸 (device sizes) 數組合併，形成用於生成圖片 srcset 的完整尺寸數組。

之所以有兩個獨立的列表，是因為 imageSizes 僅用於提供 sizes 屬性的圖片，這表示圖片的寬度小於螢幕的完整寬度。因此，imageSizes 中的尺寸都應小於 deviceSizes 中的最小尺寸。

如果未提供配置，則使用以下預設值：

module.exports = {
  images: {
    imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
  },
}

formats

預設的 圖片優化 API 會通過請求的 Accept 標頭自動檢測瀏覽器支援的圖片格式。

如果 Accept 標頭匹配多個配置的格式，則使用數組中的第一個匹配項。因此，數組的順序很重要。如果沒有匹配項（或源圖片是 動畫圖片），圖片優化 API 將回退到原始圖片的格式。

如果未提供配置，則使用以下預設值：

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

你可以通過以下配置啟用 AVIF 支援：

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

須知：

• AVIF 通常比 WebP 多花 20% 的時間編碼，但壓縮率比 WebP 高 20%。這意味著首次請求圖片時通常會較慢，但後續的快取請求會更快。
• 如果你在 Next.js 前使用代理/CDN 自託管，必須配置代理轉發 Accept 標頭。

快取行為

以下描述了預設 載入器 (loader) 的快取算法。對於所有其他載入器，請參考你的雲端供應商文檔。

圖片在請求時動態優化並存儲在 <distDir>/cache/images 目錄中。優化後的圖片文件將用於後續請求，直到過期。當請求匹配到已快取但已過期的文件時，會立即提供過期的圖片。然後在後台重新優化圖片（也稱為重新驗證）並以新的過期日期保存到快取中。

可以通過讀取 x-nextjs-cache 響應標頭的值來確定圖片的快取狀態。可能的值如下：

• MISS - 路徑不在快取中（最多發生一次，在首次訪問時）
• STALE - 路徑在快取中但已超過重新驗證時間，因此將在後台更新
• HIT - 路徑在快取中且未超過重新驗證時間

過期時間（或稱最大壽命）由 minimumCacheTTL 配置或上游圖片的 Cache-Control 標頭中較大者定義。具體來說，使用 Cache-Control 標頭的 max-age 值。如果同時找到 s-maxage 和 max-age，則優先使用 s-maxage。max-age 也會傳遞給任何下游客戶端，包括 CDN 和瀏覽器。

• 當上游圖片不包含 Cache-Control 標頭或值非常低時，可以配置 minimumCacheTTL 來增加快取時間。
• 可以配置 deviceSizes 和 imageSizes 來減少可能生成的圖片總數。
• 可以配置 格式 (formats) 來禁用多種格式，僅使用單一圖片格式。

minimumCacheTTL

你可以配置快取優化圖片的生存時間 (TTL)，單位為秒。在許多情況下，使用 靜態圖片導入 (Static Image Import) 會更好，它會自動對文件內容進行雜湊計算，並以 Cache-Control 標頭 immutable 永久快取圖片。

module.exports = {
  images: {
    minimumCacheTTL: 60,
  },
}

優化圖片的過期時間（或稱最大壽命）由 minimumCacheTTL 或上游圖片的 Cache-Control 標頭中較大者定義。

如果需要按圖片更改快取行為，可以配置 headers 來在上游圖片（例如 /some-asset.jpg，而非 /_next/image 本身）上設置 Cache-Control 標頭。

目前沒有機制可以手動使快取失效，因此最好將 minimumCacheTTL 設為較低值。否則，你可能需要手動更改 src 屬性或刪除 <distDir>/cache/images。

disableStaticImages

預設行為允許你導入靜態文件，例如 import icon from './icon.png'，然後將其傳遞給 src 屬性。

在某些情況下，如果這與其他期望導入行為不同的插件衝突，你可能希望禁用此功能。

可以在 next.config.js 中禁用靜態圖片導入：

module.exports = {
  images: {
    disableStaticImages: true,
  },
}

dangerouslyAllowSVG

預設的 載入器 (loader) 不會優化 SVG 圖片，原因有幾個。首先，SVG 是一種向量格式，意味著它可以無損縮放。其次，SVG 具有許多與 HTML/CSS 相同的功能，如果沒有適當的 內容安全策略 (Content Security Policy)，可能導致安全漏洞。

如果需要通過預設的圖片優化 API 提供 SVG 圖片，可以在 next.config.js 中設置 dangerouslyAllowSVG：

module.exports = {
  images: {
    dangerouslyAllowSVG: true,
    contentDispositionType: 'attachment',
    contentSecurityPolicy: "default-src 'self'; script-src 'none'; sandbox;",
  },
}

此外，強烈建議同時設置 contentDispositionType 以強制瀏覽器下載圖片，以及設置 contentSecurityPolicy 以防止嵌入在圖片中的腳本執行。

動畫圖片

預設的 載入器 (loader) 會自動繞過動畫圖片的優化，並以原樣提供圖片。

對動畫文件的自動檢測是盡力而為的，支援 GIF、APNG 和 WebP。如果你想明確繞過特定動畫圖片的優化，請使用 unoptimized 屬性。

響應式圖片

預設生成的 srcset 包含 1x 和 2x 圖片，以支援不同的裝置像素密度。然而，你可能希望渲染一個隨視窗拉伸的響應式圖片。在這種情況下，你需要設置 sizes 以及 style（或 className）。

你可以使用以下方法之一來渲染響應式圖片。

使用靜態導入的響應式圖片

如果源圖片不是動態的，你可以靜態導入來創建響應式圖片：

import Image from 'next/image'
import me from '../photos/me.jpg'

export default function Author() {
  return (
    <Image
      src={me}
      alt="作者的照片"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
    />
  )
}

試試看：

• 演示圖片隨視窗響應

帶有寬高比的響應式圖片

如果源圖片是動態的或遠程 URL，你還需要提供 width 和 height 來設置響應式圖片的正確寬高比：

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <Image
      src={photoUrl}
      alt="作者的照片"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
      width={500}
      height={300}
    />
  )
}

試試看：

• 演示圖片隨視窗響應

使用 fill 的響應式圖片

如果你不知道寬高比，你需要設置 fill 屬性並在父元素上設置 position: relative。可選地，你可以根據所需的拉伸或裁剪行為設置 object-fit 樣式：

import Image from 'next/image'

export default function Page({ photoUrl }) {
  return (
    <div style={{ position: 'relative', width: '500px', height: '300px' }}>
      <Image
        src={photoUrl}
        alt="作者的照片"
        sizes="500px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

試試看：

• 演示 fill 屬性

主題偵測

若您想針對淺色與深色模式顯示不同的圖片，可以建立一個封裝兩個 <Image> 元件的新元件，並根據 CSS 媒體查詢來顯示正確的圖片。

.imgDark {
  display: none;
}

@media (prefers-color-scheme: dark) {
  .imgLight {
    display: none;
  }
  .imgDark {
    display: unset;
  }
}

import styles from './theme-image.module.css'
import Image, { ImageProps } from 'next/image'

type Props = Omit<ImageProps, 'src' | 'priority' | '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} />
    </>
  )
}

小知識：預設的 loading="lazy" 行為可確保只載入正確的圖片。您不能使用 priority 或 loading="eager"，因為這會導致兩張圖片都被載入。您可以改用 fetchPriority="high"。

試試看：

• 淺色/深色模式主題偵測示範

已知瀏覽器問題

這個 next/image 元件使用瀏覽器原生的 延遲載入 (lazy loading)，在 Safari 15.4 之前的舊版瀏覽器可能會退回立即載入。當使用模糊預載佔位圖時，Safari 12 之前的舊版瀏覽器會退回空白佔位圖。當使用 width/height 為 auto 的樣式時，可能導致 Safari 15 之前不保留寬高比的舊版瀏覽器發生版面位移 (Layout Shift)。詳情請參閱 此 MDN 影片。

• Safari 15 - 16.3 在載入時會顯示灰色邊框。Safari 16.4 已修復此問題。可能的解決方案：
  • 使用 CSS @supports (font: -apple-system-body) and (-webkit-appearance: none) { img[loading="lazy"] { clip-path: inset(0.6px) } }
  • 若圖片位於首屏，可使用 priority
• Firefox 67+ 在載入時會顯示白色背景。可能的解決方案：
  • 啟用 AVIF formats
  • 使用 placeholder

版本歷史