مكون <Image> (القديم)

أمثلة

مكون الصورة القديم

بدءًا من Next.js 13، تمت إعادة كتابة مكون next/image لتحسين الأداء وتجربة المطور. لتوفير حل ترقية متوافق مع الإصدارات السابقة، تم تغيير اسم next/image القديم إلى next/legacy/image.

عرض الجديد مرجع API لـ next/image

المقارنة

مقارنة بـ next/legacy/image، يحتوي مكون next/image الجديد على التغييرات التالية:

إزالة <span> المغلف لـ <img> لصالح نسبة الأبعاد المحسوبة أصلاً
إضافة دعم لخاصية style الأساسية
- إزالة خاصية layout لصالح style أو className
- إزالة خاصية objectFit لصالح style أو className
- إزالة خاصية objectPosition لصالح style أو className
إزالة تنفيذ IntersectionObserver لصالح التحميل الكسول الأصلي
- إزالة خاصية lazyBoundary لأنه لا يوجد ما يعادلها أصليًا
- إزالة خاصية lazyRoot لأنه لا يوجد ما يعادلها أصليًا
إزالة تكوين loader لصالح خاصية loader
تغيير خاصية alt من اختيارية إلى مطلوبة
تغيير رد النداء onLoadingComplete لاستقبال مرجع لعنصر <img>

الخصائص المطلوبة

يتطلب مكون <Image /> الخصائص التالية.

src

يجب أن يكون أحد الخيارات التالية:

ملف صورة مستورد بشكل ثابت
سلسلة مسار. يمكن أن يكون هذا إما عنوان URL خارجي مطلق، أو مسار داخلي اعتمادًا على خاصية loader أو تكوين المحمل.

عند استخدام عنوان URL خارجي، يجب إضافته إلى remotePatterns في next.config.js.

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 /> عددًا من الخصائص الإضافية بخلاف تلك المطلوبة. يصف هذا القسم الخصائص الأكثر استخدامًا لمكون الصورة. يمكن العثور على تفاصيل حول الخصائص الأقل استخدامًا في قسم الخصائص المتقدمة.

layout

سلوك تخطيط الصورة مع تغير حجم نافذة العرض.

`layout`	السلوك	`srcSet`	`sizes`	هل يحتوي على غلاف ومحدد حجم
`intrinsic` (افتراضي)	تصغير ليتناسب مع عرض الحاوية، حتى حجم الصورة الأصلي	`1x`, `2x` (بناءً على imageSizes)	N/A	نعم
`fixed`	الحجم مضبوط تمامًا على `width` و `height`	`1x`, `2x` (بناءً على imageSizes)	N/A	نعم
`responsive`	التكبير ليتناسب مع عرض الحاوية	`640w`, `750w`, ... `2048w`, `3840w` (بناءً على imageSizes و deviceSizes)	`100vw`	نعم
`fill`	النمو في كلا المحورين X و Y لملء الحاوية	`640w`, `750w`, ... `2048w`, `3840w` (بناءً على imageSizes و deviceSizes)	`100vw`	نعم

عرض توضيحي لتخطيط intrinsic (افتراضي)
- عند intrinsic، ستقوم الصورة بتصغير الأبعاد لنوافذ العرض الأصغر، ولكن تحتفظ بالأبعاد الأصلية لنوافذ العرض الأكبر.
عرض توضيحي لتخطيط fixed
- عند fixed، لن تتغير أبعاد الصورة مع تغير نافذة العرض (بدون استجابة) مشابه لعنصر img الأصلي.
عرض توضيحي لتخطيط responsive
- عند responsive، ستقوم الصورة بتصغير الأبعاد لنوافذ العرض الأصغر والتكبير للنوافذ الأكبر.
- تأكد من استخدام العنصر الأب لـ display: block في ورقة الأنماط الخاصة به.
عرض توضيحي لتخطيط fill
- عند fill، ستمتد الصورة في كلا الاتجاهين العرض والارتفاع لملء أبعاد العنصر الأب، بشرط أن يكون العنصر الأب نسبيًا.
- عادة ما يتم إقران هذا مع خاصية objectFit.
- تأكد من أن العنصر الأب يحتوي على position: relative في ورقة الأنماط الخاصة به.
عرض توضيحي لصورة الخلفية

loader

دالة مخصصة تستخدم لحل عناوين URL. تعيين المحمل كخاصية على مكون الصورة يتجاوز المحمل الافتراضي المحدد في قسم images من next.config.js.

المحمل هو دالة تُرجع سلسلة عنوان URL للصورة، مع الأخذ في الاعتبار المعلمات التالية:

src
width
quality

إليك مثالاً على استخدام محمل مخصص:

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 بشكل كبير على أداء الصور التي تستخدم 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، ستكون الصورة المختارة من الخادم أكبر بثلاث مرات مما يجب أن تكون. نظرًا لأن حجم الملف يتناسب مع مربع العرض، بدون sizes، سيقوم المستخدم بتنزيل صورة أكبر بتسع مرات مما هو ضروري.

تعلم المزيد عن srcset و sizes:

web.dev
mdn

quality

جودة الصورة المحسنة، عدد صحيح بين 1 و 100 حيث 100 هو أفضل جودة. القيمة الافتراضية هي 75.

priority

عندما تكون true، ستعتبر الصورة ذات أولوية عالية وسيتم تحميلها مسبقًا. يتم تعطيل التحميل الكسول تلقائيًا للصور التي تستخدم priority.

يجب استخدام خاصية priority على أي صورة تم اكتشافها كعنصر أكبر محتوى مرئي (LCP). قد يكون من المناسب وجود عدة صور ذات أولوية، حيث يمكن أن تكون صور مختلفة عنصر LCP لأحجام نوافذ عرض مختلفة.

يجب استخدامها فقط عندما تكون الصورة مرئية فوق الطية. القيمة الافتراضية هي false.

placeholder

عنصر نائب يستخدم أثناء تحميل الصورة. القيم الممكنة هي blur أو empty. القيمة الافتراضية هي empty.

عند blur، سيتم استخدام خاصية blurDataURL كعنصر نائب. إذا كان src كائنًا من استيراد ثابت وكانت الصورة المستوردة من نوع .jpg، .png، .webp، أو .avif، فسيتم ملء blurDataURL تلقائيًا.

للصور الديناميكية، يجب عليك توفير خاصية blurDataURL. يمكن أن تساعد حلول مثل Plaiceholder في إنشاء base64.

عند empty، لن يكون هناك عنصر نائب أثناء تحميل الصورة، فقط مساحة فارغة.

جربها:

الخصائص المتقدمة

في بعض الحالات، قد تحتاج إلى استخدام متقدم. يقبل مكون <Image /> الخصائص المتقدمة التالية اختياريًا.

style

يسمح بتمرير أنماط CSS إلى عنصر الصورة الأساسي.

لاحظ أن جميع أوضاع layout تطبق أنماطها الخاصة على عنصر الصورة، وهذه الأنماط التلقائية لها الأسبقية على خاصية style.

تذكر أيضًا أن خصائص width و height المطلوبة يمكن أن تتفاعل مع التنسيق الخاص بك. إذا استخدمت التنسيق لتعديل width للصورة، فيجب عليك أيضًا تعيين height="auto"، وإلا سيتم تشويه صورتك.

objectFit

يحدد كيفية ملاءمة الصورة للحاوية الأب عند استخدام layout="fill".

يتم تمرير هذه القيمة إلى خاصية CSS object-fit للصورة src.

objectPosition

يحدد كيفية وضع الصورة داخل العنصر الأب عند استخدام layout="fill".

يتم تمرير هذه القيمة إلى خاصية CSS object-position المطبقة على الصورة.

onLoadingComplete

دالة رد نداء يتم استدعاؤها بمجرد اكتمال تحميل الصورة وإزالة العنصر النائب.

تقبل دالة onLoadingComplete معلمة واحدة، كائن يحتوي على الخصائص التالية:

loading

تنبيه: هذه الخاصية مخصصة فقط للاستخدام المتقدم. تحويل صورة للتحميل باستخدام eager عادةً ما يؤذي الأداء.

نوصي باستخدام خاصية priority بدلاً من ذلك، والتي تقوم بتحميل الصورة بفعالية لمعظم حالات الاستخدام.

سلوك تحميل الصورة. القيمة الافتراضية هي lazy.

عند lazy، يتم تأجيل تحميل الصورة حتى تصل إلى مسافة محسوبة من نافذة العرض.

عند eager، يتم تحميل الصورة على الفور.

تعلم المزيد

blurDataURL

عنوان URL للبيانات لاستخدامها كصورة نائبة قبل تحميل صورة src بنجاح. يكون فعالاً فقط عند دمجه مع placeholder="blur".

يجب أن تكون صورة مشفرة بـ base64. سيتم تكبيرها وطمسها، لذا يوصى باستخدام صورة صغيرة جدًا (10 بكسل أو أقل). قد يؤدي تضمين صور أكبر كعناصر نائبة إلى الإضرار بأداء تطبيقك.

جربها:

يمكنك أيضًا إنشاء عنوان URL لبيانات بلون ثابت لمطابقة الصورة.

lazyBoundary

سلسلة (بصيغة مشابهة لخاصية margin) تعمل كصندوق محدد يستخدم للكشف عن تقاطع نافذة العرض مع الصورة وتشغيل التحميل الكسول. القيمة الافتراضية هي "200px".

إذا كانت الصورة متداخلة داخل عنصر أب قابل للتمرير غير مستند الجذر، فستحتاج أيضًا إلى تعيين خاصية lazyRoot.

تعلم المزيد

lazyRoot

مرجع React Ref يشير إلى العنصر الأب القابل للتمرير. القيمة الافتراضية هي null (نافذة عرض المستند).

يجب أن يشير المرجع إلى عنصر DOM أو مكون React يقوم بتمرير المرجع إلى عنصر 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، سيتم تقديم الصورة المصدر كما هي دون تغيير الجودة، الحجم، أو التنسيق. القيمة الافتراضية هي false.

import Image from 'next/image'

const UnoptimizedImage = (props) => {
  return <Image {...props} unoptimized />
}

بدءًا من Next.js 12.3.0، يمكن تعيين هذا الخيار لجميع الصور عن طريق تحديث ملف next.config.js بالإعداد التالي:

next.config.js

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

خصائص أخرى

سيتم تمرير جميع الخصائص الأخرى في مكون <Image /> إلى عنصر img الأساسي باستثناء ما يلي:

srcSet. استخدم أحجام الأجهزة (Device Sizes) بدلاً من ذلك.
ref. استخدم onLoadingComplete بدلاً من ذلك.
decoding. دائمًا ما تكون قيمته "async".

خيارات التكوين

أنماط بعيدة (Remote Patterns)

لحماية تطبيقك من المستخدمين الضارين، يلزم التكوين لاستخدام الصور الخارجية. هذا يضمن أن الصور الخارجية من حسابك فقط هي التي يمكن تقديمها من واجهة برمجة تطبيقات تحسين الصور في Next.js. يمكن تكوين هذه الصور الخارجية باستخدام خاصية remotePatterns في ملف next.config.js كما يلي:

next.config.js

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

معلومة مفيدة: المثال أعلاه يضمن أن خاصية src في next/legacy/image يجب أن تبدأ بـ https://example.com/account123/ ويجب ألا تحتوي على سلسلة استعلام. أي بروتوكول آخر، أو اسم مضيف، أو منفذ، أو مسار غير متطابق سيؤدي إلى استجابة 400 Bad Request.

فيما يلي مثال لخاصية remotePatterns في ملف next.config.js باستخدام نمط حرف البدل * في hostname:

next.config.js

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

معلومة مفيدة: المثال أعلاه يضمن أن خاصية src في next/legacy/image يجب أن تبدأ بـ https://img1.example.com أو https://me.avatar.example.com أو أي عدد من النطاقات الفرعية. لا يمكن أن يحتوي على منفذ أو سلسلة استعلام. أي بروتوكول آخر أو اسم مضيف غير متطابق سيؤدي إلى استجابة 400 Bad Request.

يمكن استخدام أنماط حرف البدل لكل من pathname و hostname ولها الصيغة التالية:

* تطابق مقطع مسار واحد أو نطاق فرعي
** تطابق أي عدد من مقاطع المسار في النهاية أو النطاقات الفرعية في البداية

صيغة ** لا تعمل في منتصف النمط.

معلومة مفيدة: عند حذف protocol، port، pathname، أو search فإن حرف البدل ** يكون ضمنيًا. لا يُنصح بذلك لأنه قد يسمح لمستخدمين ضارين بتحسين عناوين URL لم تقصدها.

فيما يلي مثال لخاصية remotePatterns في ملف next.config.js باستخدام search:

next.config.js

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

معلومة مفيدة: المثال أعلاه يضمن أن خاصية src في next/legacy/image يجب أن تبدأ بـ https://assets.example.com ويجب أن تحتوي على سلسلة الاستعلام المحددة ?v=1727111025337. أي بروتوكول آخر أو سلسلة استعلام سيؤدي إلى استجابة 400 Bad Request.

النطاقات (Domains)

تحذير: أصبحت هذه الخاصية قديمة بدءًا من Next.js 14 لصالح remotePatterns الأكثر صرامة لحماية تطبيقك من المستخدمين الضارين. استخدم domains فقط إذا كنت تملك كل المحتوى المقدم من النطاق.

على غرار remotePatterns، يمكن استخدام تكوين domains لتوفير قائمة بأسماء المضيفين المسموح بها للصور الخارجية.

ومع ذلك، لا يدعم تكوين domains مطابقة أنماط حرف البدل ولا يمكنه تقييد البروتوكول أو المنفذ أو المسار.

فيما يلي مثال لخاصية domains في ملف next.config.js:

next.config.js

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

تكوين المحمل (Loader Configuration)

إذا كنت ترغب في استخدام موفر سحابي لتحسين الصور بدلاً من استخدام واجهة برمجة تطبيقات تحسين الصور المضمنة في Next.js، يمكنك تكوين loader و path في ملف next.config.js. هذا يسمح لك باستخدام عناوين URL نسبية لخاصية src للصورة وتوليد عنوان URL المطلق الصحيح لموفرك تلقائيًا.

next.config.js

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

المحملات المضمنة (Built-in Loaders)

يتم تضمين موفري تحسين الصور السحابيين التاليين:

الافتراضي: يعمل تلقائيًا مع next dev، next start، أو خادم مخصص
Vercel: يعمل تلقائيًا عند النشر على Vercel، لا حاجة للتكوين. معرفة المزيد
Imgix: loader: 'imgix'
Cloudinary: loader: 'cloudinary'
Akamai: loader: 'akamai'
مخصص: loader: 'custom' استخدم موفر سحابي مخصص عن طريق تنفيذ خاصية loader في مكون next/legacy/image

إذا كنت بحاجة إلى موفر آخر، يمكنك استخدام خاصية loader مع next/legacy/image.

لا يمكن تحسين الصور في وقت البناء باستخدام output: 'export'، فقط عند الطلب. لاستخدام next/legacy/image مع output: 'export'، ستحتاج إلى استخدام محمل مختلف عن الافتراضي. اقرأ المزيد في المناقشة.

يستخدم المحمل الافتراضي لمكون next/legacy/image squoosh لأنه سريع التثبيت ومناسب لبيئة التطوير. عند استخدام next start في بيئة الإنتاج، يوصى بشدة بتثبيت sharp عن طريق تشغيل npm i sharp في دليل مشروعك. هذا ليس ضروريًا لنشرات Vercel، حيث يتم تثبيت sharp تلقائيًا.

متقدم

التكوين التالي مخصص لحالات الاستخدام المتقدمة وعادةً لا يكون ضروريًا. إذا اخترت تكوين الخصائص أدناه، فستتجاوز أي تغييرات على الإعدادات الافتراضية لـ Next.js في التحديثات المستقبلية.

أحجام الأجهزة (Device Sizes)

إذا كنت تعرف أبعاد الأجهزة المتوقعة لمستخدميك، يمكنك تحديد قائمة بنقاط توقف عرض الجهاز باستخدام خاصية deviceSizes في next.config.js. تُستخدم هذه الأبعاد عندما يستخدم مكون next/legacy/image layout="responsive" أو layout="fill" لضمان تقديم الصورة الصحيحة لجهاز المستخدم.

إذا لم يتم توفير أي تكوين، يتم استخدام الإعداد الافتراضي التالي.

next.config.js

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

أحجام الصور (Image Sizes)

يمكنك تحديد قائمة بعروض الصور باستخدام خاصية images.imageSizes في ملف next.config.js. يتم دمج هذه العروض مع مصفوفة أحجام الأجهزة لتشكيل المصفوفة الكاملة للأحجام المستخدمة لإنشاء srcset للصور.

السبب في وجود قائمتين منفصلتين هو أن imageSizes تُستخدم فقط للصور التي توفر خاصية sizes، مما يشير إلى أن الصورة أصغر من العرض الكامل للشاشة. لذلك، يجب أن تكون جميع الأحجام في imageSizes أصغر من أصغر حجم في deviceSizes.

إذا لم يتم توفير أي تكوين، يتم استخدام الإعداد الافتراضي التالي.

next.config.js

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

التنسيقات المقبولة (Acceptable Formats)

ستكتشف واجهة برمجة تطبيقات تحسين الصور الافتراضية تلقائيًا تنسيقات الصور المدعومة من المتصفح عبر رأس Accept للطلب.

إذا تطابق رأس Accept مع أكثر من تنسيق واحد من التنسيقات المكونة، يتم استخدام أول تطابق في المصفوفة. لذلك، ترتيب المصفوفة مهم. إذا لم يكن هناك تطابق (أو إذا كانت الصورة المصدر متحركة)، ستعود واجهة برمجة تطبيقات تحسين الصور إلى تنسيق الصورة الأصلي.

إذا لم يتم توفير أي تكوين، يتم استخدام الإعداد الافتراضي التالي.

next.config.js

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

يمكنك تمكين دعم AVIF بالتكوين التالي.

next.config.js

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

معلومة مفيدة: عادةً ما يستغرق ترميز AVIF وقتًا أطول بنسبة 20٪ ولكنه يضغط بنسبة 20٪ أصغر مقارنة بـ WebP. هذا يعني أن المرة الأولى التي يتم فيها طلب صورة، ستكون عادةً أبطأ ثم الطلبات اللاحقة التي يتم تخزينها مؤقتًا ستكون أسرع.

سلوك التخزين المؤقت (Caching Behavior)

يصف ما يلي خوارزمية التخزين المؤقت للمحمل الافتراضي. بالنسبة لجميع المحملات الأخرى، يرجى الرجوع إلى وثائق موفر السحابة الخاص بك.

يتم تحسين الصور ديناميكيًا عند الطلب وتخزينها في دليل <distDir>/cache/images. سيتم تقديم ملف الصورة المحسن للطلبات اللاحقة حتى انتهاء الصلاحية. عند إجراء طلب يتطابق مع ملف مخزن مؤقتًا ولكن منتهي الصلاحية، يتم تقديم الصورة المنتهية الصلاحية على الفور. ثم يتم تحسين الصورة مرة أخرى في الخلفية (يُسمى أيضًا إعادة التحقق) وحفظها في ذاكرة التخزين المؤقت مع تاريخ انتهاء الصلاحية الجديد.

يمكن تحديد حالة التخزين المؤقت للصورة عن طريق قراءة قيمة رأس الاستجابة x-nextjs-cache (x-vercel-cache عند النشر على Vercel). القيم الممكنة هي كما يلي:

MISS - المسار غير موجود في ذاكرة التخزين المؤقت (يحدث مرة واحدة على الأكثر، في الزيارة الأولى)
STALE - المسار موجود في ذاكرة التخزين المؤقت ولكن تجاوز وقت إعادة التحقق لذلك سيتم تحديثه في الخلفية
HIT - المسار موجود في ذاكرة التخزين المؤقت ولم يتجاوز وقت إعادة التحقق

يتم تعريف انتهاء الصلاحية (أو بالأحرى الحد الأقصى للعمر) إما عن طريق تكوين minimumCacheTTL أو رأس Cache-Control للصورة الأصلية، أيهما أكبر. على وجه التحديد، يتم استخدام قيمة max-age لرأس Cache-Control. إذا تم العثور على كل من s-maxage و max-age، فإن s-maxage يكون مفضلًا. يتم أيضًا تمرير max-age إلى أي عملاء لاحقين بما في ذلك شبكات CDN والمتصفحات.

يمكنك تكوين minimumCacheTTL لزيادة مدة التخزين المؤقت عندما لا يتضمن رأس Cache-Control للصورة الأصلية أو كانت القيمة منخفضة جدًا.
يمكنك تكوين deviceSizes و imageSizes لتقليل العدد الإجمالي للصور الممكن إنشاؤها.
يمكنك تكوين التنسيقات لتعطيل تنسيقات متعددة لصالح تنسيق صورة واحد.

الحد الأدنى لوقت التخزين المؤقت (Minimum Cache TTL)

يمكنك تكوين وقت البقاء (TTL) بالثواني للصور المحسنة المخزنة مؤقتًا. في كثير من الحالات، من الأفضل استخدام استيراد صورة ثابت (Static Image Import) والذي سيقوم تلقائيًا بتجزئة محتويات الملف وتخزين الصورة مؤقتًا إلى الأبد مع رأس Cache-Control بقيمة immutable.

next.config.js

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

يتم تعريف انتهاء الصلاحية (أو الحد الأقصى للعمر) للصورة المحسنة إما عن طريق minimumCacheTTL أو رأس Cache-Control للصورة الأصلية، أيهما أكبر.

إذا كنت بحاجة إلى تغيير سلوك التخزين المؤقت لكل صورة، يمكنك تكوين headers لتعيين رأس Cache-Control على الصورة الأصلية (مثل /some-asset.jpg، وليس /_next/image نفسه).

لا توجد آلية لإبطال التخزين المؤقت في هذا الوقت، لذا من الأفضل الحفاظ على minimumCacheTTL منخفضًا. وإلا قد تحتاج إلى تغيير خاصية src يدويًا أو حذف <distDir>/cache/images.

تعطيل الاستيراد الثابت (Disable Static Imports)

السلوك الافتراضي يسمح لك باستيراد ملفات ثابتة مثل import icon from './icon.png' ثم تمرير ذلك إلى خاصية src.

في بعض الحالات، قد ترغب في تعطيل هذه الميزة إذا كانت تتعارض مع ملحقات أخرى تتوقع أن يكون الاستيراد مختلفًا.

يمكنك تعطيل استيراد الصور الثابتة داخل ملف next.config.js:

next.config.js

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

السماح بصيغة SVG بشكل خطير (Dangerously Allow SVG)

لا يقوم المحمل الافتراضي بتحسين صور SVG لعدة أسباب. أولاً، SVG هو تنسيق متجه مما يعني أنه يمكن تغيير حجمه دون فقدان الجودة. ثانيًا، يحتوي SVG على العديد من الميزات نفسها مثل HTML/CSS، مما قد يؤدي إلى ثغرات أمنية بدون رؤوس سياسة أمان المحتوى (CSP) المناسبة.

لذلك، نوصي باستخدام خاصية unoptimized عندما تكون خاصية src معروفة بأنها SVG. يحدث هذا تلقائيًا عندما ينتهي src بـ ".svg".

ومع ذلك، إذا كنت بحاجة إلى تقديم صور SVG باستخدام واجهة برمجة تطبيقات تحسين الصور الافتراضية، يمكنك تعيين dangerouslyAllowSVG داخل ملف next.config.js:

next.config.js

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

بالإضافة إلى ذلك، يوصى بشدة أيضًا بتعيين contentDispositionType لإجبار المتصفح على تنزيل الصورة، وكذلك contentSecurityPolicy لمنع تنفيذ البرامج النصية المضمنة في الصورة.

الصور المتحركة (Animated Images)

سيقوم المحمل الافتراضي تلقائيًا بتجاوز تحسين الصور للصور المتحركة وتقديم الصورة كما هي.

الكشف التلقائي عن الملفات المتحركة هو أفضل جهد ويدعم GIF وAPNG وWebP. إذا كنت ترغب في تجاوز تحسين الصور بشكل صريح لصورة متحركة معينة، استخدم خاصية unoptimized.

سجل الإصدارات

الإصدار	التغييرات
`v13.0.0`	تمت إعادة تسمية `next/image` إلى `next/legacy/image`

On this page