logoNext.js 繁體中文
文件部落格學習
介紹/API 參考文檔/元件/Image

Image

Next.js 的 Image 元件擴展了 HTML 的 <img> 元素，提供自動圖片優化功能。

app/page.js
import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="作者的照片"
    />
  )
}

須知事項：如果您使用的是 Next.js 13 之前的版本，您應該參考 next/legacy/image 文件，因為元件名稱已變更。

參考

屬性

以下是可用的屬性：

屬性範例類型狀態
srcsrc="/profile.png"字串必填
altalt="作者的照片"字串必填
widthwidth={500}整數 (px)-
heightheight={500}整數 (px)-
fillfill={true}布林值-
loaderloader={imageLoader}函式-
sizessizes="(max-width: 768px) 100vw, 33vw"字串-
qualityquality={80}整數 (1-100)-
prioritypriority={true}布林值-
placeholderplaceholder="blur"字串-
stylestyle={{objectFit: "contain"}}物件-
onLoadingCompleteonLoadingComplete={img => done())}函式已棄用
onLoadonLoad={event => done())}函式-
onErroronError(event => fail()}函式-
loadingloading="lazy"字串-
blurDataURLblurDataURL="data:image/jpeg..."字串-
overrideSrcoverrideSrc="/seo.png"字串-

src

圖片的來源。可以是以下之一：

內部路徑字串。

<Image src="/profile.png" />

絕對外部 URL (必須配置 remotePatterns)。

<Image src="https://example.com/profile.png" />

靜態導入。

import profile from './profile.png'

export default function Page() {
  return <Image src={profile} />
}

alt

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

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

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

了解更多關於 圖片無障礙指南。

width 和 height

width 和 height 屬性代表圖片的 固有 大小 (以像素為單位)。此屬性用於推斷瀏覽器用來為圖片保留空間的正確 寬高比，避免載入時的版面位移。它不決定圖片的 渲染大小，這由 CSS 控制。

<Image src="/profile.png" width={500} height={500} />

您 必須 設定 width 和 height 屬性，除非：

如果高度和寬度未知，建議使用 fill 屬性。

fill

一個布林值，使圖片擴展至父元素的大小。

<Image src="/profile.png" fill={true} />

定位：

  • 父元素 必須 設定 position: "relative"、"fixed" 或 "absolute"。
  • 預設情況下，<img> 元素使用 position: "absolute"。

物件擬合：

如果沒有對圖片套用樣式，圖片會拉伸以適應容器。您可以使用 objectFit 來控制裁剪和縮放。

  • "contain"：圖片會縮小以適應容器並保持寬高比。
  • "cover"：圖片會填滿容器並被裁剪。

了解更多關於 position 和 object-fit。

loader

用於生成圖片 URL 的自訂函式。該函式接收以下參數，並返回圖片的 URL 字串：

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="作者的照片"
      width={500}
      height={500}
    />
  )
}

或者，您可以在 next.config.js 中使用 loaderFile 配置來設定應用程式中所有 next/image 的實例，而無需傳遞屬性。

sizes

定義圖片在不同斷點的大小。瀏覽器使用此來從生成的 srcset 中選擇最合適的大小。

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 應在以下情況下使用：

  • 圖片使用 fill 屬性
  • 使用 CSS 使圖片具有響應式

如果缺少 sizes，瀏覽器會假設圖片與視口一樣寬 (100vw)。這可能導致下載不必要的大圖片。

此外，sizes 影響 srcset 的生成：

  • 沒有 sizes：Next.js 生成有限的 srcset (例如 1x, 2x)，適用於固定大小的圖片。
  • 有 sizes：Next.js 生成完整的 srcset (例如 640w, 750w 等)，針對響應式佈局進行優化。

了解更多關於 srcset 和 sizes 的資訊：web.dev 和 mdn。

quality

一個介於 1 和 100 之間的整數，設定優化圖片的品質。較高的值會增加檔案大小和視覺逼真度。較低的值會減少檔案大小，但可能影響清晰度。

// 預設品質為 75
<Image quality={75} />

如果您在 next.config.js 中配置了 qualities，該值必須與允許的條目之一匹配。

須知事項：如果原始圖片已經是低品質，設定高品質值會增加檔案大小而不會改善外觀。

style

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

const imageStyle = {
  borderRadius: '50%',
  border: '1px solid #fff',
  width: '100px',
  height: 'auto',
}

export default function ProfileImage() {
  return <Image src="..." style={imageStyle} />
}

須知事項：如果您使用 style 屬性來設定自訂寬度，請確保也設定 height: 'auto' 以保持圖片的寬高比。

priority

一個布林值，指示是否應預載圖片。

// 預設 priority 為 false
<Image priority={false} />
  • true：預載 圖片。停用延遲載入。
  • false：延遲載入圖片。

使用時機：

不使用時機：

  • 當使用 loading 屬性時 (會觸發警告)。

loading

控制圖片何時開始載入。

// 預設為 lazy
<Image loading="lazy" />
  • lazy：延遲載入圖片，直到它到達與視口的計算距離。
  • eager：立即載入圖片，無論其在頁面中的位置如何。

僅在您希望確保圖片立即載入時使用 eager。

了解更多關於 loading 屬性。

placeholder

指定在圖片載入時使用的佔位符，改善感知載入效能。

// 預設為 empty
<Image placeholder="empty" />
  • empty：圖片載入時沒有佔位符。
  • blur：使用圖片的模糊版本作為佔位符。必須與 blurDataURL 屬性一起使用。
  • data:image/...：使用 Data URL 作為佔位符。

範例：

了解更多關於 placeholder 屬性。

blurDataURL

一個 Data URL，在圖片成功載入之前用作佔位圖片。可以自動設定或與 placeholder="blur" 屬性一起使用。

<Image placeholder="blur" blurDataURL="..." />

圖片會自動放大和模糊，因此建議使用非常小的圖片 (10px 或更小)。

自動

如果 src 是 jpg、png、webp 或 avif 檔案的靜態導入，blurDataURL 會自動新增 — 除非圖片是動畫。

手動設定

如果圖片是動態或遠端的，您必須自行提供 blurDataURL。要生成一個，您可以使用：

過大的 blurDataURL 可能會影響效能。保持其小而簡單。

範例：

onLoad

一個回呼函式，在圖片完全載入且 佔位符 已移除時呼叫。

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

回呼函式將被呼叫，並帶有一個參數，即事件，其 target 引用底層的 <img> 元素。

onError

一個回呼函式，在圖片載入失敗時呼叫。

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

unoptimized

一個布林值，指示是否應優化圖片。這對於無法從優化中受益的圖片很有用，例如小圖片 (小於 1KB)、向量圖片 (SVG) 或動畫圖片 (GIF)。

import Image from 'next/image'

const UnoptimizedImage = (props) => {
  // 預設為 false
  return <Image {...props} unoptimized />
}
  • true：原始圖片將從 src 直接提供，不改變品質、大小或格式。
  • false：原始圖片將被優化。

自 Next.js 12.3.0 起，可以通過更新 next.config.js 來為所有圖片設定此屬性：

next.config.js
module.exports = {
  images: {
    unoptimized: true,
  },
}

overrideSrc

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

input.js
<Image src="/profile.jpg" />
output.html
<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 目的，例如圖片排名或避免重新爬取。

input.js
<Image src="/profile.jpg" overrideSrc="/override.jpg" />
output.html
<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
<Image decoding="async" />
  • async：非同步解碼圖片，允許其他內容在其完成前呈現。
  • sync：同步解碼圖片，與其他內容一起原子性呈現。
  • auto：無偏好。瀏覽器選擇最佳方法。

了解更多關於 decoding 屬性。

其他屬性

<Image /> 元件的其他屬性將傳遞給底層的 img 元素，除了以下例外：

已棄用屬性

onLoadingComplete

警告：已在 Next.js 14 中棄用，請改用 onLoad。

一個回調函式，當圖片完全載入且 佔位符 (placeholder) 已被移除時觸發。

該回調函式會接收一個參數，即底層 <img> 元素的參考。

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

配置選項

您可以在 next.config.js 中配置圖片元件。以下是可用的選項：

localPatterns

在 next.config.js 中使用 localPatterns 來允許優化特定本地路徑的圖片並封鎖其他所有路徑。

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

上述範例將確保 next/image 的 src 屬性必須以 /assets/images/ 開頭且不得有查詢字串。嘗試優化其他路徑將回傳 400 錯誤請求。

remotePatterns

在 next.config.js 中使用 remotePatterns 來允許特定外部路徑的圖片並封鎖其他所有路徑。這確保只有來自您帳號的外部圖片能被提供。

next.config.js
module.exports = {
  images: {
    remotePatterns: [new URL('https://example.com/account123/**')],
  },
}

如果使用 15.3.0 之前的版本，您可以使用物件配置 remotePatterns：

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

上述範例將確保 next/image 的 src 屬性必須以 https://example.com/account123/ 開頭且不得有查詢字串。任何其他協定、主機名稱、端口或不匹配的路徑將回傳 400 錯誤請求。

萬用字元模式：

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

  • * 匹配單一路徑段或子網域
  • ** 匹配任意數量的路徑段（在末尾）或子網域（在開頭）。此語法不能在模式中間使用。
next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com',
        port: '',
        search: '',
      },
    ],
  },
}

這允許像 image.example.com 這樣的子網域。查詢字串和自訂端口仍會被封鎖。

須知：當省略 protocol、port、pathname 或 search 時，會隱含使用萬用字元 **。這不建議使用，因為可能允許惡意行為者優化您無意允許的網址。

查詢字串：

您也可以使用 search 屬性限制查詢字串：

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

上述範例將確保 next/image 的 src 屬性必須以 https://assets.example.com 開頭且必須有確切的查詢字串 ?v=1727111025337。任何其他協定或查詢字串將回傳 400 錯誤請求。

loaderFile

loaderFiles 允許您使用自訂圖片優化服務替代 Next.js。

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

路徑必須相對於專案根目錄。該檔案必須導出一個預設函式，回傳一個 URL 字串：

my/image/loader.js
export default function myImageLoader({ src, width, quality }) {
  return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}

範例：

或者，您可以使用 loader 屬性 來配置每個 next/image 實例。

deviceSizes

deviceSizes 允許您指定裝置寬度斷點列表。當 next/image 元件使用 sizes 屬性時，這些寬度用於確保為使用者的裝置提供正確的圖片。

如果未提供配置，則使用以下預設值：

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

imageSizes

imageSizes 允許您指定圖片寬度列表。這些寬度與 裝置尺寸 (device sizes) 陣列連接，形成用於生成圖片 srcset 的完整尺寸陣列。

如果未提供配置，則使用以下預設值：

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

imageSizes 僅用於提供 sizes 屬性的圖片，這表示圖片小於螢幕的完整寬度。因此，imageSizes 中的尺寸都應小於 deviceSizes 中的最小尺寸。

qualities

qualities 允許您指定圖片品質值列表。

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

在上述範例中，只允許三種品質：25、50 和 75。如果 quality 屬性與此陣列中的值不匹配，圖片將失敗並回傳 400 錯誤請求。

formats

formats 允許您指定要使用的圖片格式列表。

next.config.js
module.exports = {
  images: {
    // 預設值
    formats: ['image/webp'],
  },
}

Next.js 透過請求的 Accept 標頭自動檢測瀏覽器支援的圖片格式，以確定最佳輸出格式。

如果 Accept 標頭匹配多個配置的格式，則使用陣列中的第一個匹配項。因此，陣列順序很重要。如果沒有匹配項（或來源圖片是動畫），則使用原始圖片的格式。

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

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

須知：

  • 我們仍建議在大多數情況下使用 WebP。
  • AVIF 通常需要多 50% 的時間編碼，但與 WebP 相比壓縮率高出 20%。這意味著首次請求圖片時通常會較慢，但後續快取的請求會更快。
  • 如果您在 Next.js 前使用 Proxy/CDN 自託管，必須配置 Proxy 轉發 Accept 標頭。

minimumCacheTTL

minimumCacheTTL 允許您配置快取優化圖片的存留時間 (TTL)（以秒為單位）。在許多情況下，最好使用 靜態圖片匯入 (Static Image Import)，它會自動雜湊檔案內容並使用 Cache-Control 標頭 immutable 永久快取圖片。

如果未提供配置，則使用以下預設值：

next.config.js
module.exports = {
  images: {
    minimumCacheTTL: 60, // 1 分鐘
  },
}

您可以增加 TTL 以減少重新驗證的次數並可能降低成本：

next.config.js
module.exports = {
  images: {
    minimumCacheTTL: 2678400, // 31 天
  },
}

優化圖片的過期時間（或更確切地說是最大存留時間）由 minimumCacheTTL 或上游圖片的 Cache-Control 標頭中較大者決定。

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

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

disableStaticImages

disableStaticImages 允許您停用靜態圖片匯入。

預設行為允許您匯入靜態檔案，例如 import icon from './icon.png'，然後將其傳遞給 src 屬性。在某些情況下，如果與其他期望匯入行為不同的插件衝突，您可能希望停用此功能。

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

next.config.js
module.exports = {
  images: {
    disableStaticImages: true,
  },
}

dangerouslyAllowSVG

dangerouslyAllowSVG 允許您提供 SVG 圖片。

next.config.js
module.exports = {
  images: {
    dangerouslyAllowSVG: true,
  },
}

預設情況下，Next.js 不會優化 SVG 圖片，原因如下：

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

<Image src="/my-image.svg" unoptimized />

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

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

contentDispositionType

contentDispositionType 允許您配置 Content-Disposition 標頭。

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

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

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

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

已棄用的配置選項

domains

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

類似於 remotePatterns，domains 配置可用於提供允許的外部圖片主機名稱列表。然而，domains 配置不支援萬用字元模式匹配，也無法限制協定、端口或路徑名稱。

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

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

函式

getImageProps

getImageProps 函式可用於獲取將傳遞給底層 <img> 元素的屬性，並將它們傳遞給其他元件、樣式、畫布等。

import { getImageProps } from 'next/image'

const props = getImageProps({
  src: 'https://example.com/image.jpg',
  alt: 'A scenic mountain view',
  width: 1200,
  height: 800,
})

function ImageWithCaption() {
  return (
    <figure>
      <img {...props} />
      <figcaption>A scenic mountain view</figcaption>
    </figure>
  )
}

這也避免了呼叫 React useState()，因此可以提高效能，但不能與 placeholder 屬性一起使用，因為佔位符將永遠不會被移除。

已知瀏覽器錯誤

next/image 元件使用瀏覽器原生的 延遲載入 (lazy loading)，對於 Safari 15.4 之前的舊版瀏覽器可能會回退到立即載入。當使用模糊佔位符時，Safari 12 之前的舊版瀏覽器會回退到空白佔位符。當使用 width/height 為 auto 的樣式時，可能導致 Safari 15 之前不 保留寬高比 的舊版瀏覽器發生 版面位移 (Layout Shift)。更多詳情，請參閱 此 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) } }
    • 如果圖片在首屏 (above the fold)，使用 priority

  • Firefox 67+ 在載入時顯示白色背景。可能的解決方案：

範例

圖片樣式

為 Image 元件設定樣式類似於為普通 <img> 元素設定樣式，但需要記住一些準則：

使用 className 或 style，而非 styled-jsx。在多數情況下，我們建議使用 className 屬性。這可以是匯入的 CSS 模組 (CSS Module)、全域樣式表 (global stylesheet) 等。

import styles from './styles.module.css'

export default function MyImage() {
  return <Image className={styles.image} src="/my-image.png" alt="My Image" />
}

您也可以使用 style 屬性來設定行內樣式。

export default function MyImage() {
  return (
    <Image style={{ borderRadius: '8px' }} src="/my-image.png" alt="My Image" />
  )
}

當使用 fill 時，父元素必須具有 position: relative 或 display: block。這對於在該佈局模式下正確渲染圖片元素是必要的。

<div style={{ position: 'relative' }}>
  <Image fill src="/my-image.png" alt="My Image" />
</div>

您不能使用 styled-jsx，因為它的作用域僅限於當前元件（除非您將樣式標記為 global）。

靜態匯出時使用響應式圖片

當你匯入靜態圖片時，Next.js 會根據檔案自動設定其寬度和高度。你可以透過設定樣式來讓圖片具有響應式效果：

Responsive image filling the width and height of its parent container
import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Responsive() {
  return (
    <div style={{ display: 'flex', flexDirection: 'column' }}>
      <Image
        alt="Mountains"
        // 匯入圖片時會
        // 自動設定寬度和高度
        src={mountains}
        sizes="100vw"
        // 讓圖片顯示為全寬
        // 並保持其長寬比
        style={{
          width: '100%',
          height: 'auto',
        }}
      />
    </div>
  )
}

使用遠端 URL 的響應式圖片

如果來源圖片是動態或遠端 URL，你必須提供 width 和 height 屬性，以便 Next.js 能計算長寬比：

components/page.js
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 屬性 並將 objectFit 屬性設為 cover。這會讓圖片填滿其父容器的整個寬度。

Grid of images filling parent container width
import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Fill() {
  return (
    <div
      style={{
        display: 'grid',
        gridGap: '8px',
        gridTemplateColumns: 'repeat(auto-fit, minmax(400px, auto))',
      }}
    >
      <div style={{ position: 'relative', width: '400px' }}>
        <Image
          alt="Mountains"
          src={mountains}
          fill
          sizes="(min-width: 808px) 50vw, 100vw"
          style={{
            objectFit: 'cover', // cover, contain, none
          }}
        />
      </div>
      {/* 網格中的其他圖片... */}
    </div>
  )
}

背景圖片

使用 fill 屬性讓圖片覆蓋整個螢幕區域：

Background image taking full width and height of page
import Image from 'next/image'
import mountains from '../public/mountains.jpg'

export default function Background() {
  return (
    <Image
      alt="Mountains"
      src={mountains}
      placeholder="blur"
      quality={100}
      fill
      sizes="100vw"
      style={{
        objectFit: 'cover',
      }}
    />
  )
}

如需查看 Image 元件與各種樣式的使用範例，請參閱 Image 元件示範。

遠端圖片

若要使用遠端圖片，src 屬性應為 URL 字串。

app/page.js
import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="https://s3.amazonaws.com/my-bucket/profile.png"
      alt="Picture of the author"
      width={500}
      height={500}
    />
  )
}

由於 Next.js 在建置過程中無法存取遠端檔案，你需要手動提供 width、height 和可選的 blurDataURL 屬性。

width 和 height 屬性用於推斷圖片的正確長寬比，並避免圖片載入時的版面位移。width 和 height 並不會決定圖片檔案的渲染大小。

為了安全地允許優化圖片，請在 next.config.js 中定義支援的 URL 模式列表。盡可能具體以防止惡意使用。例如，以下配置僅允許來自特定 AWS S3 儲存桶的圖片：

next.config.js
module.exports = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: 's3.amazonaws.com',
        port: '',
        pathname: '/my-bucket/**',
        search: '',
      },
    ],
  },
}

主題偵測

如果你想為淺色和深色模式顯示不同的圖片，可以建立一個新元件，包裝兩個 <Image> 元件，並根據 CSS 媒體查詢顯示正確的圖片。

components/theme-image.module.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() 提供不同的 src、width、height 和 quality 屬性。

app/page.js
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 函數，以優化背景圖片。

app/page.js
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>
  )
}

版本歷史

版本變更內容
v15.3.0remotePatterns 新增支援 URL 物件陣列。
v15.0.0contentDispositionType 配置預設值變更為 attachment。
v14.2.23新增 qualities 配置。
v14.2.15新增 decoding 屬性與 localPatterns 配置。
v14.2.14新增 remotePatterns.search 屬性。
v14.2.0新增 overrideSrc 屬性。
v14.1.0getImageProps() 進入穩定狀態。
v14.0.0onLoadingComplete 屬性與 domains 配置標記為棄用。
v13.4.14placeholder 屬性新增支援 data:/image...。
v13.2.0新增 contentDispositionType 配置。
v13.0.6新增 ref 屬性。
v13.0.0next/image 導入路徑更名為 next/legacy/image。next/future/image 導入路徑更名為 next/image。提供 自動重構工具 可安全自動重命名導入路徑。移除 <span> 包裝元素。移除 layout、objectFit、objectPosition、lazyBoundary、lazyRoot 屬性。alt 屬性改為必填。onLoadingComplete 現在接收 img 元素參照。移除內建載入器配置。
v12.3.0remotePatterns 與 unoptimized 配置進入穩定狀態。
v12.2.0新增實驗性 remotePatterns 與實驗性 unoptimized 配置。移除 layout="raw"。
v12.1.1新增 style 屬性。新增實驗性支援 layout="raw"。
v12.1.0新增 dangerouslyAllowSVG 與 contentSecurityPolicy 配置。
v12.0.9新增 lazyRoot 屬性。
v12.0.0新增 formats 配置。
新增 AVIF 支援。
包裝元素從 <div> 改為 <span>。
v11.1.0新增 onLoadingComplete 與 lazyBoundary 屬性。
v11.0.0src 屬性新增支援靜態導入。
新增 placeholder 屬性。
新增 blurDataURL 屬性。
v10.0.5新增 loader 屬性。
v10.0.1新增 layout 屬性。
v10.0.0正式引入 next/image。

Head

使用內建的 Head 元件為頁面的 `head` 添加自訂元素。

Image (舊版)

使用舊版 Image 元件實現向後相容的圖片最佳化。

On this page