<Image>

此 API 參考文件將協助您了解如何使用 Image 元件提供的 屬性 和 組態選項。有關功能和用法，請參閱 Image 元件 頁面。

import Image from 'next/image'
 
export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
    />
  )
}

屬性

以下是 Image 元件可用的屬性摘要

必填屬性

Image 組件需要以下屬性：src、width、height 和 alt。

import Image from 'next/image'
 
export default function Page() {
  return (
    <div>
      <Image
        src="/profile.png"
        width={500}
        height={500}
        alt="Picture of the author"
      />
    </div>
  )
}

src

必須為下列其中一項

• 一個靜態匯入的圖片檔案
• 一個路徑字串。這可以是絕對的外部 URL，或根據loader屬性而定的內部路徑。

使用外部 URL 時，你必須將它加入next.config.js中的remotePatterns。

width

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

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

height

height 屬性表示以像素為單位的已呈現高度，因此它會影響圖片顯示的大小。

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

alt

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

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

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

深入了解

選用 Props

<Image /> 元件除了必要的屬性外，還接受許多其他屬性。本節說明 Image 元件最常使用的屬性。有關較少使用的屬性的詳細資訊，請參閱 進階 Props 部分。

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

須知：使用接受函式的 props（例如 loader）時，需要使用 Client Components 來序列化提供的函式。

或者，您可以在 next.config.js 中使用 loaderFile 設定，設定應用程式中 next/image 的每個執行個體，而無須傳遞 props。

fill

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

布林值，會讓圖片填滿父元素，這在 width 和 height 未知時很有用。

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

預設情況下，img 元素會自動指定 position: "absolute" 樣式。

如果未對影像套用任何樣式，影像會延伸以符合容器。您可能會偏好設定 object-fit: "contain"，以使影像以 letterbox 方式符合容器並保留長寬比。

或者，object-fit: "cover" 會使影像填滿整個容器，並裁剪以保留長寬比。為了讓這看起來正確，應將 overflow: "hidden" 樣式指定給父元素。

如需更多資訊，另請參閱

• position
• object-fit
• object-position

sizes

類似媒體查詢的字串，提供有關影像在不同中斷點的寬度的資訊。sizes 的值會大幅影響使用 fill 或 設定為具有回應式大小的影像 的效能。

sizes 屬性服務於與影像效能相關的兩個重要目的

• 首先，瀏覽器會使用 sizes 的值來決定從 next/image 自動產生的 srcset 中下載哪個尺寸的圖片。瀏覽器在選擇時，還不知道圖片在頁面上的尺寸，因此會選擇與視窗相同或更大的圖片。sizes 屬性可讓您告訴瀏覽器，圖片實際上會小於全螢幕。如果您沒有在具有 fill 屬性的圖片中指定 sizes 值，則會使用預設值 100vw（全螢幕寬度）。
• 其次，sizes 屬性會變更自動產生的 srcset 值的行為。如果沒有 sizes 值，則會產生一個適合固定尺寸圖片（1x/2x/等）的小型 srcset。如果已定義 sizes，則會產生一個適合回應式圖片（640w/750w/等）的大型 srcset。如果 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，圖像將被視為高優先順序，並會預載。使用 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/... 時，資料 URL 將用作圖像載入時的佔位符。

當為 empty 時，圖像載入時不會有佔位符，只會有空白。

試用

• 展示 blur 佔位符
• 展示資料 URL placeholder 屬性的閃爍效果
• 展示 blurDataURL 屬性的顏色效果

進階屬性

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

style

允許將 CSS 樣式傳遞給底層影像元素。

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
}
 
export default function ProfileImage() {
  return <Image src="..." style={imageStyle} />
}

請記住，必要的寬度和高度屬性可能會與您的樣式互動。如果您使用樣式來修改影像的寬度，您也應該將其高度設定為 auto 以保留其內在的長寬比，否則您的影像將會失真。

onLoadingComplete

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

警告：自 Next.js 14 起已棄用，建議使用 onLoad。

當圖片完全載入且佔位符已移除後呼叫的回呼函式。

回呼函式會呼叫一個參數，即對應的底層 <img> 元素的參考。

須知：使用接受函式的屬性（例如 onLoadingComplete）需要使用Client Components來序列化提供的函式。

onLoad

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

當圖片完全載入且佔位符已移除後呼叫的回呼函式。

回呼函式會呼叫一個參數，即包含參考對應的底層 <img> 元素的 target 的事件。

須知：使用接受函式的屬性（例如 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

一個 資料 URL，用作在 src 圖片成功載入前的佔位圖片。僅在與 placeholder="blur" 結合使用時才會生效。

必須是 base64 編碼的圖片。它將會被放大和模糊處理，因此建議使用非常小的圖片（10 像素或更小）。將較大的圖片作為佔位圖片可能會損害應用程式的效能。

試用

• 展示預設的 blurDataURL 屬性
• 展示 blurDataURL 屬性的顏色效果

你也可以 產生一個純色資料 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。請改用 裝置大小。
• decoding。它永遠是 "async"。

組態選項

除了屬性之外，你可以在 next.config.js 中組態 Image 元件。下列選項可供使用

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',
        port: '',
      },
    ],
  },
}

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

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

• * 匹配單一路徑區段或子網域
• ** 匹配結尾的任何數量的路徑區段或開頭的子網域

** 語法不適用於模式的中間。

須知：省略 protocol、port 或 pathname 時，會暗示萬用字元 **。不建議這麼做，因為這可能允許惡意行為者最佳化您無意圖的網址。

domains

警告：自 Next.js 14 起已棄用，建議使用嚴格的 remotePatterns，以保護您的應用程式免於惡意使用者。只有當您擁有從網域提供的全部內容時，才使用 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 的每個執行個體。

範例

• 自訂圖片載入器設定

須知：自訂圖片載入器檔案（接受函式）需要使用 用戶端元件 來序列化提供的函式。

進階

以下設定適用於進階使用案例，通常不需要。如果你選擇設定下列屬性，你將會覆寫 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 屬性，指定圖片寬度清單。這些寬度會與 裝置尺寸 陣列串接，以形成用於產生圖片 srcset 的尺寸陣列。

有兩個獨立清單的原因是 imageSizes 僅用於提供 sizes prop 的圖片，這表示圖片小於螢幕的全寬。因此，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 編碼通常需要多 20% 的時間，但與 WebP 相比，它壓縮的檔案小 20%。這表示第一次要求圖片時，通常會比較慢，然後後續快取的要求會比較快。
• 如果你在 Next.js 前面使用 Proxy/CDN 自行主機，你必須設定 Proxy 轉發 Accept 標頭。

快取行為

以下說明預設 loader 的快取演算法。對於所有其他 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 和瀏覽器。

• 你可以設定 minimumCacheTTL，以在上游圖片不包含 Cache-Control 標頭或其值非常低時增加快取持續時間。
• 你可以設定 deviceSizes 和 imageSizes，以減少可能產生的圖片總數。
• 你可以設定 格式，以停用多種格式，改用單一圖片格式。

minimumCacheTTL

你可以設定快取最佳化圖片的生存時間 (TTL)，單位為秒。在許多情況下，最好使用 靜態圖片匯入，它會自動對檔案內容進行雜湊，並使用 immutable 的 Cache-Control 標頭永久快取圖片。

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

最佳化圖片的到期時間（或更準確地說是最大年齡）由 minimumCacheTTL 或上游圖片 Cache-Control 標頭定義，以較大者為準。

如果你需要針對每張圖片變更快取行為，你可以設定 標頭，以在上游圖片（例如 /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 相同的功能，這可能會導致沒有適當的 內容安全政策 (CSP) 標頭 而產生漏洞。

因此，我們建議在 src 屬性已知為 SVG 時使用 unoptimized 屬性。當 src 以 ".svg" 結尾時，這會自動發生。

但是，如果你需要使用預設的圖片最佳化 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="Picture of the author"
      sizes="100vw"
      style={{
        width: '100%',
        height: 'auto',
      }}
    />
  )
}

試用

• 示範回應視窗大小的圖片

具有長寬比的回應式圖片

如果原始圖片是動態的或遠端網址，您還需要提供 width 和 height 來設定回應式圖片的正確長寬比

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 屬性，並在父項上設定 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="Picture of the author"
        sizes="500px"
        fill
        style={{
          objectFit: 'contain',
        }}
      />
    </div>
  )
}

試用

• 示範 fill 屬性

主題偵測 CSS

如果您想要為淺色和深色模式顯示不同的圖片，您可以建立一個新的元件，將兩個 <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"。

試用

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

getImageProps

對於更進階的使用案例，你可以呼叫 getImageProps() 來取得會傳遞到底層 <img> 元素的 props，然後將它們傳遞給另一個元件、樣式、畫布等。

這也可以避免呼叫 React useState()，因此可以提升效能，但它不能與 placeholder props 一起使用，因為 placeholder 永遠不會被移除。

主題偵測圖片

如果你想要為明暗模式顯示不同的圖片，你可以使用 <picture> 元素，根據使用者的 偏好的色彩配置 顯示不同的圖片。

import { getImageProps } from 'next/image'
 
export default function Page() {
  const common = { alt: 'Theme Example', width: 800, height: 400 }
  const {
    props: { srcSet: dark },
  } = getImageProps({ ...common, src: '/dark.png' })
  const {
    props: { srcSet: light, ...rest },
  } = getImageProps({ ...common, src: '/light.png' })
 
  return (
    <picture>
      <source media="(prefers-color-scheme: dark)" srcSet={dark} />
      <source media="(prefers-color-scheme: light)" srcSet={light} />
      <img {...rest} />
    </picture>
  )
}

藝術指導

如果你想要為行動裝置和桌機顯示不同的圖片，有時稱為 藝術指導，你可以提供不同的 src

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>
  )
}

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>
  )
}