圖片

須知：如果您使用的 Next.js 版本早於 13，您會需要使用 next/legacy/image 文件，因為該組件已重新命名。

此 API 參考將協助您了解如何使用圖片組件可用的 props 和 設定選項。如需功能和使用方式，請參閱圖片組件頁面。

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

Props

以下是圖片組件可用 props 的摘要

必要的 Props

圖片組件需要下列屬性：src、alt、width 和 height (或 fill)。

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 prop 的內部路徑。

使用預設 loader 時，也請考慮來源圖片的以下事項

• 當 src 是外部 URL 時，您也必須設定 remotePatterns
• 當 src 是動畫或不明格式 (JPEG、PNG、WebP、AVIF、GIF、TIFF) 時，圖片將按原樣提供
• 當 src 是 SVG 格式時，除非啟用 unoptimized 或 dangerouslyAllowSVG，否則將會被封鎖

width

width 屬性代表圖片的固有寬度（以像素為單位）。此屬性用於推斷圖片的正確長寬比，並避免載入期間的版面配置偏移。它不會決定圖片的渲染大小，圖片的渲染大小由 CSS 控制，類似於 HTML <img> 標籤中的 width 屬性。

為必要屬性，但靜態導入的圖片或具有 fill 屬性的圖片除外。

height

height 屬性代表圖片的固有高度（以像素為單位）。此屬性用於推斷圖片的正確長寬比，並避免載入期間的版面配置偏移。它不會決定圖片的渲染大小，圖片的渲染大小由 CSS 控制，類似於 HTML <img> 標籤中的 height 屬性。

為必要屬性，但靜態導入的圖片或具有 fill 屬性的圖片除外。

須知

• width 和 height 屬性結合使用，以決定圖片的長寬比，瀏覽器會使用此長寬比在圖片載入前預留空間。
• 固有大小並不總是表示瀏覽器中的渲染大小，渲染大小將由父容器決定。例如，如果父容器小於固有大小，則圖片將縮小以符合容器。
• 當寬度和高度未知時，您可以使用 fill 屬性。

alt

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

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

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

瞭解更多資訊

選用的 Props

<Image /> 組件接受許多必要屬性以外的其他屬性。本節說明圖片組件最常用的屬性。如需有關較少使用的屬性的詳細資訊，請參閱進階 Props 章節。

loader

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

loader 是一個函式，可針對圖片傳回 URL 字串，並提供下列參數

• src
• width
• quality

以下是使用自訂 loader 的範例

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

或者，您可以使用 next.config.js 中的 loaderFile 設定來設定應用程式中 next/image 的每個實例，而無需傳遞 prop。

fill

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

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

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

依預設，img 元素將自動指派 position: "absolute" 樣式。

如果未將任何樣式套用至圖片，則圖片將拉伸以符合容器。您可能偏好設定 object-fit: "contain"，讓圖片以信箱模式符合容器並保留長寬比。

或者，object-fit: "cover" 將使圖片填滿整個容器並裁剪以保留長寬比。

如需更多資訊，另請參閱

• position
• object-fit
• object-position

sizes

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

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

• 首先，瀏覽器會使用 sizes 的值來決定要從 next/image 自動產生的 srcset 下載哪個大小的圖片。當瀏覽器選擇時，它還不知道頁面上圖片的大小，因此它會選擇與視窗大小相同或更大的圖片。sizes 屬性可讓您告訴瀏覽器圖片實際上會小於全螢幕。如果您未在使用 fill 屬性的圖片中指定 sizes 值，則會使用預設值 100vw (全螢幕寬度)。
• 其次，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 大小，從伺服器選取的圖片將是其所需寬度的 3 倍。由於檔案大小與寬度的平方成正比，若沒有 sizes，使用者將下載比必要大小大 9 倍的圖片。

瞭解更多關於 srcset 和 sizes 的資訊

• web.dev
• mdn

quality

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

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

如果在 next.config.js 中定義了 qualities 設定，則 quality prop 必須符合設定中定義的值之一。

須知：如果原始來源圖片的品質已經很低，則將 quality prop 設定得太高可能會導致產生的最佳化圖片大於原始來源圖片。

priority

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

若為 true，Next.js 將預先載入圖片。對於使用 priority 的圖片，會自動停用延遲載入。如果也使用了 loading 屬性並將其設定為 lazy，則無法使用 priority 屬性。loading 屬性僅適用於進階使用案例。當需要 priority 時，請移除 loading。

您應在偵測為最大內容繪製 (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 prop 示範微光效果
• 使用 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

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

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

當圖片完全載入且 placeholder 已移除後，會調用此回呼函式。

回呼函式將被調用，並帶有一個參數，即底層 <img> 元素的參考。

onLoad

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

當圖片完全載入且 placeholder 已移除後，會調用此回呼函式。

回呼函式將被調用，並帶有一個參數，即 Event 物件，其 target 屬性參考到底層的 <img> 元素。

onError

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

如果圖片載入失敗，則會調用此回呼函式。

loading

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

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

當設定為 lazy 時，會延遲載入圖片，直到圖片到達與 viewport 的計算距離。

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

深入瞭解 loading 屬性。

blurDataURL

作為 src 圖片成功載入前的預留位置圖片使用的 Data URL。僅在與 placeholder="blur" 結合使用時生效。

必須是 base64 編碼的圖片。它將被放大和模糊，因此建議使用非常小的圖片（10px 或更小）。包含較大的圖片作為預留位置可能會損害您的應用程式效能。

試用看看

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

您也可以產生純色 Data URL以符合圖片的顏色。

unoptimized

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

若為 true，來源圖片將從 src 以原始狀態提供，而不會變更品質、大小或格式。預設為 false。

這對於不適合最佳化的圖片很有用，例如小圖片（小於 1KB）、向量圖片 (SVG) 或動畫圖片 (GIF)。

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

overrideSrc

當提供 src 屬性給 <Image> 元件時，會自動為產生的 <img> 產生 srcset 和 src 屬性。

<Image src="/me.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/_next/image?url=%2Fme.jpg&w=828&q=75"
/>

在某些情況下，不希望產生 src 屬性，您可能希望使用 overrideSrc 屬性覆寫它。

例如，當將現有網站從 <img> 升級到 <Image> 時，您可能希望為了 SEO 目的（例如圖片排名或避免重新爬取）而維持相同的 src 屬性。

<Image src="/me.jpg" overrideSrc="/override.jpg" />

<img
  srcset="
    /_next/image?url=%2Fme.jpg&w=640&q=75 1x,
    /_next/image?url=%2Fme.jpg&w=828&q=75 2x
  "
  src="/override.jpg"
/>

decoding

給瀏覽器的提示，指示在呈現其他內容更新之前，是否應等待圖片解碼。預設為 async。

可能的值如下

• async - 非同步解碼圖片，並允許在完成之前呈現其他內容。
• sync - 同步解碼圖片，以便與其他內容進行原子呈現。
• auto - 對於解碼模式沒有偏好；由瀏覽器決定最佳方式。

深入瞭解 decoding 屬性。

其他屬性

<Image /> 元件上的其他屬性將會傳遞至底層的 img 元素，但以下屬性除外

• srcSet。請改用裝置尺寸。

設定選項

除了屬性之外，您還可以在 next.config.js 中設定 Image 元件。以下選項可用

localPatterns

您可以選擇性地在 next.config.js 檔案中設定 localPatterns，以允許最佳化特定路徑並封鎖所有其他路徑。

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

小提示：上面的範例將確保 next/image 的 src 屬性必須以 /assets/images/ 開頭，且不得包含查詢字串。嘗試最佳化任何其他路徑將會回應 400 Bad Request。

remotePatterns

為了保護您的應用程式免受惡意使用者侵害，使用外部圖片需要進行設定。這確保只有來自您帳戶的外部圖片可以從 Next.js Image Optimization API 提供。這些外部圖片可以使用 next.config.js 檔案中的 remotePatterns 屬性進行設定，如下所示

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

小提示：上面的範例將確保 next/image 的 src 屬性必須以 https://example.com/account123/ 開頭，且不得包含查詢字串。任何其他協定、主機名稱、埠或不符的路徑將會回應 400 Bad Request。

以下是 next.config.js 檔案中使用萬用字元模式的 remotePatterns 屬性範例，在 hostname 中

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

小提示：上面的範例將確保 next/image 的 src 屬性必須以 https://img1.example.com 或 https://me.avatar.example.com 或任何數量的子網域開頭。它不能有埠或查詢字串。任何其他協定或不符的主機名稱將會回應 400 Bad Request。

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

• * 比對單一路徑區段或子網域
• ** 比對結尾的任意數量路徑區段或開頭的子網域

** 語法在模式中間不起作用。

小提示：當省略 protocol、port、pathname 或 search 時，則暗示使用萬用字元 **。不建議這樣做，因為這可能會允許惡意行為者最佳化您不希望最佳化的 URL。

以下是 next.config.js 檔案中使用 search 的 remotePatterns 屬性範例

module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 'assets.example.com',
        search: '?v=1727111025337',
      },
    ],
  },
}

小提示：上面的範例將確保 next/image 的 src 屬性必須以 https://assets.example.com 開頭，且必須具有完全相同的查詢字串 ?v=1727111025337。任何其他協定或查詢字串將會回應 400 Bad Request。

domains

警告：自 Next.js 14 起已棄用，建議改用嚴格的 remotePatterns，以保護您的應用程式免受惡意使用者侵害。只有在您擁有從網域提供的所有內容時，才使用 domains。

與 remotePatterns 類似，domains 設定可用於提供外部圖片的允許主機名稱清單。

但是，domains 設定不支援萬用字元模式比對，且無法限制協定、埠或路徑名稱。

以下是 next.config.js 檔案中 domains 屬性的範例

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

loaderFile

如果您想要使用雲端供應商來最佳化圖片，而不是使用 Next.js 內建的 Image Optimization API，您可以在 next.config.js 中設定 loaderFile，如下所示

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

這必須指向相對於您的 Next.js 應用程式根目錄的檔案。該檔案必須匯出一個預設函式，該函式會傳回字串，例如

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 屬性的圖片，這表示圖片小於螢幕的完整寬度。因此，imageSizes 中的尺寸都應小於 deviceSizes 中最小的尺寸。

如果未提供任何設定，則會使用以下預設值。

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

qualities

預設的 Image Optimization API 將自動允許從 1 到 100 的所有品質。如果您希望限制允許的品質，您可以將設定新增至 next.config.js。

module.exports = {
  images: {
    qualities: [25, 50, 75],
  },
}

在上面的範例中，僅允許三個品質：25、50 和 75。如果 quality 屬性與此陣列中的值不符，則圖片將會失敗並顯示 400 Bad Request。

formats

預設的 Image Optimization API 將自動偵測瀏覽器支援的圖片格式，透過請求的 Accept 標頭，以判斷最佳輸出格式。

如果 Accept 標頭符合多個已設定的格式，則會使用陣列中的第一個符合項。因此，陣列順序很重要。如果沒有符合項（或來源圖片是動畫），Image Optimization API 將會回退到原始圖片的格式。

如果未提供任何設定，則會使用以下預設值。

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

您可以啟用 AVIF 支援，如果瀏覽器不支援 AVIF，則將回退到 src 圖片的原始格式

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

須知:

• 我們仍然建議在大多數情況下使用 WebP。
• AVIF 通常需要多 50% 的時間來編碼，但與 WebP 相比，壓縮後的大小會小 20%。這表示第一次請求圖片時，通常會比較慢，然後後續快取的請求會更快。
• 如果您使用 Proxy/CDN 自行託管在 Next.js 前面，您必須設定 Proxy 以轉發 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 和瀏覽器。

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

minimumCacheTTL

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

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

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

如果您需要變更每個圖片的快取行為，您可以設定 headers，以在上游圖片上設定 Cache-Control 標頭（例如 /some-asset.jpg，而不是 /_next/image 本身）。

目前沒有使快取失效的機制，因此最好將 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" 結尾時，會自動發生這種情況。

但是，如果您需要使用預設的 Image Optimization API 提供 SVG 圖片，您可以在 next.config.js 內設定 dangerouslyAllowSVG

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

此外，強烈建議您也設定 contentDispositionType 以強制瀏覽器下載圖片，並設定 contentSecurityPolicy 以防止嵌入在圖片中的腳本執行。

contentDispositionType

預設的 loader 將 Content-Disposition 標頭設定為 attachment，以增加保護，因為 API 可以提供任意的遠端圖片。

預設值為 attachment，這會強制瀏覽器在直接瀏覽時下載圖片。當 dangerouslyAllowSVG 為 true 時，這一點尤其重要。

您可以選擇性地設定 inline，以允許瀏覽器在直接瀏覽時渲染圖片，而無需下載。

module.exports = {
  images: {
    contentDispositionType: 'inline',
  },
}

動畫圖片

預設的 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: '300px', height: '500px' }}>
      <Image
        src={photoUrl}
        alt="Picture of the author"
        sizes="300px"
        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"。

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

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