<Image>

注意事項：如果您使用的 Next.js 版本早於 13，您需要使用 next/legacy/image 文件，因為該元件已重新命名。

此 API 參考將幫助您了解如何使用 屬性 (props) 和 設定選項 來設定 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"
    />
  )
}

屬性 (Props)

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

必要屬性

Image 元件需要以下屬性：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 屬性。

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

• 當 src 是外部 URL 時，您也必須設定 remotePatterns
• 當 src 是 動畫 或不是已知格式 (JPEG、PNG、WebP、AVIF、GIF、TIFF) 時，圖片將會按原樣提供
• 當 `src` 為 SVG 格式時，除非啟用 unoptimized 或 [dangerouslyAllowSVG`](#dangerouslyallowsvg)，否則將會被阻擋。

width

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

此屬性為必需，但 靜態匯入的圖片 或具有 fill 屬性 的圖片除外。

height

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

此屬性為必需，但 靜態匯入的圖片 或具有 fill 屬性 的圖片除外。

注意事項

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

alt

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

它應該包含可以在不改變頁面含義的情況下取代圖片的文字。它不應作為圖片的補充說明，也不應重複圖片上方或下方標題中已提供的資訊。

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

了解更多

選用屬性

<Image /> 元件除了必要屬性之外，還接受許多額外屬性。本節說明 Image 元件最常用的屬性。關於較少使用的屬性，請參閱進階屬性章節。

loader

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

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

• 來源 (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 的實例，而無需傳遞屬性。

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。

priority

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

當設定為 true 時，圖片將被視為高優先級並預先載入。使用 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 佔位圖範例
• 使用資料網址 placeholder 屬性的 shimmer 效果範例
• 使用 blurDataURL 屬性的顏色效果範例

進階屬性

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

style

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

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

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

onLoadingComplete

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

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

圖片完全載入且 預留位置 已移除後將會呼叫的回呼函式。

此回呼函式將會以一個參數呼叫，該參數為底層 <img> 元素的參考。

onLoad

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

圖片完全載入且 預留位置 已移除後將會呼叫的回呼函式。

此回呼函式會以一個參數呼叫，該參數為事件物件，其中包含一個指向底層 <img> 元素的 target 屬性。

onError

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

圖片載入失敗時將會呼叫的回呼函式。

loading

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

圖片的載入行為。預設為 lazy（延遲載入）。

設定為 lazy 時，將延遲載入圖片，直到它到達距離視埠的計算距離。

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

深入了解 loading 屬性。

blurDataURL

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

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

試用看看

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

您也可以產生純色資料網址來匹配圖片。

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

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> 時，您可能希望保留相同的 src 屬性以利於 SEO，例如圖片排名或避免重新爬取。

<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。請改用 裝置尺寸。

設定選項localPatterns

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

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

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

remotePatterns

為了保護您的應用程式免受惡意使用者的攻擊，需要進行設定才能使用外部圖片。這可確保只有來自您帳戶的外部圖片才能透過 Next.js 圖片最佳化 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 檔案中使用萬用字元模式設定 hostname 的 remotePatterns 屬性範例

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 內建的圖片最佳化 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],
  },
}

formats

預設的圖片最佳化 API 會自動透過請求的 Accept 標頭偵測瀏覽器支援的圖片格式，以決定最佳的輸出格式。

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

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

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

您可以啟用 AVIF 支援，並在以下設定中 fallback 到 WebP。

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

注意事項:

• AVIF 編碼通常需要多花 50% 的時間，但與 WebP 相比，它可以壓縮小 20%。這表示第一次請求圖片時，速度通常會比較慢，而後續快取的請求速度會比較快。
• 如果您使用 Proxy/CDN 在 Next.js 之前自行託管，則必須設定 Proxy 轉發 Accept 標頭。

快取行為

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

圖片會根據請求動態最佳化，並儲存在 <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)，單位為秒。在大多數情況下，最好使用靜態圖片導入，它會自動雜湊檔案內容，並使用 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

next.config.js

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