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 的範例

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

要知道：使用像 loader 這樣接受函式的 props，需要使用用戶端元件來序列化提供的函式。

或者，您可以使用 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

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

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 屬性
• 示範搭配 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)} />

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

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

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

小知識：使用諸如 onLoadingComplete 等接受函式的屬性，需要使用客戶端元件 來序列化提供的函式。

onLoad

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

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

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

小知識：使用諸如 onLoad 等接受函式的屬性，需要使用 客戶端元件 來序列化提供的函式。

onError

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

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

小知識：使用諸如 onError 等接受函式的屬性，需要使用 客戶端元件 來序列化提供的函式。

loading

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

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

當設為 lazy 時，會延遲載入圖片，直到圖片到達視窗可見範圍的計算距離內。

當設為 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 應用程式根目錄的檔案。該檔案必須匯出一個預設函式，該函式會傳回字串，例如

'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 屬性的圖片，這表示圖片小於螢幕的全寬。因此，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 標頭。

快取行為

以下說明預設 載入器 的快取演算法。對於所有其他載入器，請參閱您的雲端供應商的文件。

圖片會在請求時動態最佳化，並儲存在 <distDir>/cache/images 目錄中。最佳化後的圖片檔案將會用於後續請求，直到達到到期時間為止。當發出的請求與快取但已到期的檔案相符時，會立即提供過期的圖片。然後，圖片會在背景中再次最佳化（也稱為重新驗證）並儲存到快取中，並帶有新的到期日。

圖片的快取狀態可以透過讀取 x-nextjs-cache 回應標頭的值來判斷。可能的值如下

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

到期時間（或更確切地說是 Max Age）由 minimumCacheTTL 設定或上游圖片 Cache-Control 標頭定義，以較大者為準。具體來說，會使用 Cache-Control 標頭的 max-age 值。如果同時找到 s-maxage 和 max-age，則優先使用 s-maxage。max-age 也會傳遞到任何下游用戶端，包括 CDN 和瀏覽器。

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

minimumCacheTTL

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

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

最佳化圖片的到期時間（或更確切地說是 Max Age）由 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

預設的 載入器 基於幾個原因不會最佳化 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

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

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

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

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

動畫圖片

預設的 載入器 將會自動繞過動畫圖片的 Image Optimization，並完整提供圖片。

動畫檔案的自動偵測是盡力而為，並支援 GIF、APNG 和 WebP。如果您想明確繞過給定動畫圖片的 Image Optimization，請使用 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',
      }}
    />
  )
}

試用看看

• 示範圖片對視窗響應

具有長寬比的響應式圖片

如果來源圖片是動態或遠端 URL，您還需要提供 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"。

試用看看

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

getImageProps

對於更進階的使用情境，您可以呼叫 getImageProps() 以取得將傳遞到底層 <img> 元素的屬性，並將它們傳遞到另一個元件、樣式、畫布等。

這也能避免呼叫 React useState()，因此可以帶來更好的效能，但它不能與 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>
  )
}

美術指導

如果您想為行動裝置和桌上型電腦顯示不同的圖片，有時稱為 美術指導，您可以為 getImageProps() 提供不同的 src、width、height 和 quality 屬性。

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

背景 CSS

您甚至可以將 srcSet 字串轉換為 image-set() CSS 函數，以最佳化背景圖片。

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

已知瀏覽器錯誤

此 next/image 元件使用瀏覽器原生 延遲載入，對於 Safari 15.4 之前的舊版瀏覽器，可能會回退為及早載入。當使用模糊化預留位置時，Safari 12 之前的舊版瀏覽器將會回退為空白預留位置。當樣式與 width/height 的 auto 一起使用時，可能會在 Safari 15 之前不 保留長寬比 的舊版瀏覽器上造成 版面配置偏移。如需更多詳細資訊，請參閱 這部 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

版本歷史記錄