Image (Legacy)

從 Next.js 13 開始，next/image 組件已重新編寫，以改善效能和開發人員體驗。為了提供向後相容的升級解決方案，舊的 next/image 已重新命名為 next/legacy/image。

檢視新的 next/image API 參考

比較

與 next/legacy/image 相比，新的 next/image 組件有以下變更

• 移除 <span> 包裹層，改用 原生計算的長寬比
• 新增對標準 style 屬性的支援
  • 移除 layout 屬性，改用 style 或 className
  • 移除 objectFit 屬性，改用 style 或 className
  • 移除 objectPosition 屬性，改用 style 或 className
• 移除 IntersectionObserver 實作，改用 原生延遲載入
  • 移除 lazyBoundary 屬性，因為沒有原生對應項
  • 移除 lazyRoot 屬性，因為沒有原生對應項
• 變更 loader 設定，改用 loader 屬性
• 將 alt 屬性從選用改為必要
• 變更 onLoadingComplete 回呼以接收 <img> 元素的參考

必要屬性

<Image /> 組件需要以下屬性。

src

必須是以下其中之一

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

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

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

width

width 屬性可以代表渲染寬度或原始寬度 (以像素為單位)，取決於 layout 和 sizes 屬性。

當使用 layout="intrinsic" 或 layout="fixed" 時，width 屬性代表渲染寬度 (以像素為單位)，因此會影響圖片顯示的大小。

當使用 layout="responsive"、layout="fill" 時，width 屬性代表原始寬度 (以像素為單位)，因此只會影響長寬比。

width 屬性為必要，靜態匯入的圖片或具有 layout="fill" 的圖片除外。

height

height 屬性可以代表渲染高度或原始高度 (以像素為單位)，取決於 layout 和 sizes 屬性。

當使用 layout="intrinsic" 或 layout="fixed" 時，height 屬性代表渲染高度 (以像素為單位)，因此會影響圖片顯示的大小。

當使用 layout="responsive"、layout="fill" 時，height 屬性代表原始高度 (以像素為單位)，因此只會影響長寬比。

height 屬性為必要，靜態匯入的圖片或具有 layout="fill" 的圖片除外。

選用屬性

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

layout

圖片在視窗大小變更時的版面配置行為。

• 示範 intrinsic 版面配置 (預設)
  • 當為 intrinsic 時，圖片會為較小的視窗縮放尺寸，但為較大的視窗維持原始尺寸。
• 示範 fixed 版面配置
  • 當為 fixed 時，圖片尺寸不會隨著視窗變更而改變 (沒有回應式行為)，類似於原生 img 元素。
• 示範 responsive 版面配置
  • 當為 responsive 時，圖片會為較小的視窗縮放尺寸，並為較大的視窗放大尺寸。
  • 請確保父元素在其樣式表中使用 display: block。
• 示範 fill 版面配置
  • 當為 fill 時，圖片會將寬度和高度都拉伸到父元素的尺寸，前提是父元素是相對定位。
  • 這通常與 objectFit 屬性配對使用。
  • 請確保父元素在其樣式表中有 position: relative。
• 示範背景圖片

loader

用於解析 URL 的自訂函式。在 Image 組件上將 loader 設定為屬性，會覆寫在 next.config.js 的 images 區段中定義的預設 loader。

loader 是一個函式，會傳回圖片的 URL 字串，並提供以下參數

• src
• width
• quality

以下是使用自訂 loader 的範例

import Image from 'next/legacy/image'
 
const myLoader = ({ src, width, quality }) => {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}
 
const MyImage = (props) => {
  return (
    <Image
      loader={myLoader}
      src="me.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

sizes

一個字串，提供圖片在不同斷點的寬度資訊。sizes 的值將大幅影響使用 layout="responsive" 或 layout="fill" 的圖片效能。對於使用 layout="intrinsic" 或 layout="fixed" 的圖片，它將被忽略。

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

首先，瀏覽器會使用 sizes 的值，從 next/legacy/image 自動產生的來源集中，判斷要下載的圖片尺寸。當瀏覽器選擇時，它還不知道圖片在頁面上的尺寸，因此它會選擇與視窗大小相同或更大的圖片。sizes 屬性可讓您告訴瀏覽器，圖片實際上會小於全螢幕。如果您未指定 sizes 值，則會使用預設值 100vw (全螢幕寬度)。

其次，會剖析 sizes 值，並用於修剪自動建立的來源集中的值。如果 sizes 屬性包含例如 50vw 等代表視窗寬度百分比的尺寸，則會修剪來源集，使其不包含任何太小而永遠不需要的值。

例如，如果您知道您的樣式設定會導致圖片在行動裝置上為全寬，在平板電腦上為雙欄式版面配置，在桌上型電腦顯示器上為三欄式版面配置，您應該包含類似以下的 sizes 屬性

import Image from 'next/legacy/image'
const Example = () => (
  <div className="grid-element">
    <Image
      src="/example.png"
      layout="fill"
      sizes="(max-width: 768px) 100vw,
              (max-width: 1200px) 50vw,
              33vw"
    />
  </div>
)

此範例 sizes 可能對效能指標產生顯著影響。如果沒有 33vw 尺寸，從伺服器選取的圖片會比需要的寬 3 倍。由於檔案大小與寬度的平方成正比，因此如果沒有 sizes，使用者會下載比必要尺寸大 9 倍的圖片。

深入瞭解 srcset 和 sizes

• web.dev
• mdn

quality

最佳化圖片的品質，介於 1 到 100 的整數，其中 100 為最佳品質。預設為 75。

priority

若為 true，圖片將被視為高優先順序，並預先載入。對於使用 priority 的圖片，會自動停用延遲載入。

您應該在任何偵測為最大內容繪製 (LCP)元素的圖片上使用 priority 屬性。有多個優先順序圖片可能是適當的，因為不同的圖片可能是不同視窗尺寸的 LCP 元素。

僅應在圖片在首頁可見時使用。預設為 false。

placeholder

在圖片載入時使用的預留位置。可能的值為 blur 或 empty。預設為 empty。

當為 blur 時，blurDataURL 屬性將用作預留位置。如果 src 是來自 靜態匯入的物件，且匯入的圖片為 .jpg、.png、.webp 或 .avif，則會自動填入 blurDataURL。

對於動態圖片，您必須提供 blurDataURL 屬性。例如 Plaiceholder 等解決方案可以協助產生 base64。

當為 empty 時，圖片載入時將不會有預留位置，只有空白空間。

試用看看

• 示範 blur 預留位置
• 使用 blurDataURL 屬性示範微光效果
• 使用 blurDataURL 屬性示範色彩效果

進階屬性

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

style

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

請注意，所有 layout 模式都會將自己的樣式套用至圖片元素，而這些自動樣式的優先順序高於 style 屬性。

另請記住，必要的 width 和 height 屬性可能會與您的樣式設定互動。如果您使用樣式設定來修改圖片的 width，您也必須將 height="auto" 樣式設定為 auto，否則您的圖片會失真。

objectFit

定義使用 layout="fill" 時，圖片將如何適應其父容器。

此值會傳遞至 src 圖片的 object-fit CSS 屬性。

objectPosition

定義使用 layout="fill" 時，圖片在其父元素中的定位方式。

這個值會傳遞至套用在圖片上的 object-position CSS 屬性。

onLoadingComplete

這是一個回呼函式，會在圖片完全載入且 佔位符 移除後被調用。

onLoadingComplete 函式接受一個參數，一個具有以下屬性的物件

• naturalWidth
• naturalHeight

loading

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

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

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

了解更多

blurDataURL

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

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

試用看看

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

您也可以 產生純色 Data URL 以匹配圖片。

lazyBoundary

一個字串（語法與 margin 屬性類似），作為邊界框使用，用於偵測視窗與圖片的交集，並觸發 lazy loading。預設值為 "200px"。

如果圖片嵌套在根文件以外的可滾動父元素中，您也需要指定 lazyRoot 屬性。

了解更多

lazyRoot

一個 React Ref，指向可滾動的父元素。預設值為 null（文件視窗）。

Ref 必須指向一個 DOM 元素或一個 React 組件，該組件會 將 Ref 轉發 到底層的 DOM 元素。

指向 DOM 元素的範例

import Image from 'next/legacy/image'
import React from 'react'
 
const Example = () => {
  const lazyRoot = React.useRef(null)
 
  return (
    <div ref={lazyRoot} style={{ overflowX: 'scroll', width: '500px' }}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </div>
  )
}

指向 React 組件的範例

import Image from 'next/legacy/image'
import React from 'react'
 
const Container = React.forwardRef((props, ref) => {
  return (
    <div ref={ref} style={{ overflowX: 'scroll', width: '500px' }}>
      {props.children}
    </div>
  )
})
 
const Example = () => {
  const lazyRoot = React.useRef(null)
 
  return (
    <Container ref={lazyRoot}>
      <Image lazyRoot={lazyRoot} src="/one.jpg" width="500" height="500" />
      <Image lazyRoot={lazyRoot} src="/two.jpg" width="500" height="500" />
    </Container>
  )
}

了解更多

unoptimized

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

其他屬性

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

• srcSet。請改用裝置尺寸。
• ref。請改用 onLoadingComplete。
• decoding。它始終為 "async"。

配置選項

遠端模式

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

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

**小知識**：上面的範例將確保 next/legacy/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/legacy/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/legacy/image 的 src 屬性必須以 https://assets.example.com 開頭，且必須具有完全相同的查詢字串 ?v=1727111025337。任何其他協定或查詢字串都將回應 400 Bad Request。

網域

**警告**：自 Next.js 14 起已棄用，轉而使用更嚴格的 remotePatterns，以保護您的應用程式免受惡意使用者攻擊。僅當您擁有從網域提供的所有內容時，才使用 domains。

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

然而，domains 配置不支援萬用字元模式匹配，並且無法限制協定、埠號或路徑名稱。

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

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

加載器配置

如果您想要使用雲端供應商來優化圖片，而不是使用 Next.js 內建的圖片優化 API，您可以在 next.config.js 檔案中配置 loader 和 path 前綴。這允許您為 Image src 使用相對 URL，並自動為您的供應商產生正確的絕對 URL。

module.exports = {
  images: {
    loader: 'imgix',
    path: 'https://example.com/myaccount/',
  },
}

內建加載器

包含以下圖片優化雲端供應商

• 預設：使用 next dev、next start 或自訂伺服器時自動運作
• Vercel：當您部署在 Vercel 上時自動運作，無需任何配置。了解更多
• Imgix：loader: 'imgix'
• Cloudinary：loader: 'cloudinary'
• Akamai：loader: 'akamai'
• 自訂：loader: 'custom'，透過在 next/legacy/image 組件上實作 loader 屬性來使用自訂雲端供應商

如果您需要不同的供應商，您可以將 loader 屬性與 next/legacy/image 一起使用。

圖片無法在使用 output: 'export' 建置時進行優化，只能按需優化。若要將 next/legacy/image 與 output: 'export' 一起使用，您需要使用與預設值不同的加載器。在討論中閱讀更多...

進階

以下配置適用於進階使用案例，通常不是必要的。如果您選擇配置以下屬性，您將覆寫未來更新中對 Next.js 預設值的任何變更。

裝置尺寸

如果您知道使用者預期的裝置寬度，您可以使用 next.config.js 中的 deviceSizes 屬性指定裝置寬度斷點的清單。當 next/legacy/image 組件使用 layout="responsive" 或 layout="fill" 時，會使用這些寬度，以確保為使用者的裝置提供正確的圖片。

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

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

圖片尺寸

您可以使用 next.config.js 檔案中的 images.imageSizes 屬性指定圖片寬度清單。這些寬度會與 裝置尺寸 陣列串連，以形成用於產生圖片 srcsets 的完整尺寸陣列。

存在兩個獨立清單的原因是 imageSizes 僅用於提供 sizes 屬性的圖片，這表示圖片小於螢幕的完整寬度。**因此，imageSizes 中的尺寸應全部小於 deviceSizes 中的最小尺寸。**

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

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

可接受的格式

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

如果 Accept 標頭與多個已配置的格式匹配，則會使用陣列中的第一個匹配項。因此，陣列順序很重要。如果沒有匹配項（或來源圖片是動畫），則圖片優化 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（在 Vercel 上部署時為 x-vercel-cache）回應標頭的值來確定。可能的值如下

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

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

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

最小快取 TTL

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

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

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

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

目前沒有機制可以使快取失效，因此最好保持較低的 minimumCacheTTL。否則，您可能需要手動變更 src 屬性或刪除 <distDir>/cache/images。

停用靜態匯入

預設行為允許您匯入靜態檔案，例如 import icon from './icon.png'，然後將其傳遞給 src 屬性。

在某些情況下，如果此功能與期望匯入行為不同的其他外掛程式衝突，您可能希望停用此功能。

您可以在 next.config.js 內停用靜態圖片匯入

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

危險地允許 SVG

預設的 加載器 基於幾個原因不優化 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 以防止圖片中嵌入的腳本執行。

contentDispositionType

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

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

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

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

動畫圖片

預設的 加載器 將自動繞過動畫圖片的圖片優化，並按原樣提供圖片。

動畫檔案的自動偵測是盡力而為，並支援 GIF、APNG 和 WebP。如果您想明確繞過特定動畫圖片的圖片優化，請使用 unoptimized 屬性。

版本歷史