الصورة (الإصدار القديم)

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

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

عند استخدام المحمّل الافتراضي، ضع في الاعتبار أيضًا ما يلي للصور المصدر:

عندما يكون src عنوان URL خارجي، يجب أيضًا تكوين أنماط بعيدة
عندما يكون src متحركًا أو ليس بتنسيق معروف (JPEG، PNG، WebP، AVIF، GIF، TIFF)، سيتم تقديم الصورة كما هي
عندما يكون src بتنسيق SVG، سيتم حظره ما لم يتم تمكين unoptimized أو dangerouslyAllowSVG

العرض

يمكن أن تمثل خاصية width إما العرض المعروض أو العرض الأصلي بالبكسل، اعتمادًا على خصائص layout و sizes.

عند استخدام layout="intrinsic" أو layout="fixed"، تمثل خاصية width العرض المعروض بالبكسل، لذا سيؤثر على حجم الصورة الظاهر.

عند استخدام layout="responsive" أو layout="fill"، تمثل خاصية width العرض الأصلي بالبكسل، لذا سيؤثر فقط على نسبة العرض إلى الارتفاع.

خاصية width مطلوبة، باستثناء الصور المستوردة بشكل ثابت، أو تلك التي تحتوي على layout="fill".

الارتفاع

يمكن أن تمثل خاصية height إما الارتفاع المعروض أو الارتفاع الأصلي بالبكسل، اعتمادًا على خصائص layout و sizes.

عند استخدام layout="intrinsic" أو layout="fixed"، تمثل خاصية height الارتفاع المعروض بالبكسل، لذا سيؤثر على حجم الصورة الظاهر.

عند استخدام layout="responsive" أو layout="fill"، تمثل خاصية height الارتفاع الأصلي بالبكسل، لذا سيؤثر فقط على نسبة العرض إلى الارتفاع.

خاصية height مطلوبة، باستثناء الصور المستوردة بشكل ثابت، أو تلك التي تحتوي على layout="fill".

الخصائص الاختيارية

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

التخطيط

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

`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 في ورقة الأنماط الخاصة به.
عرض توضيحي لصورة الخلفية

المحمّل

دالة مخصصة تستخدم لحل عناوين 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

الجودة

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

الأولوية

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

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

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

العنصر النائب

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

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

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

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

جربها:

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

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

النمط

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

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

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

objectFit

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

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

objectPosition

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

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

onLoadingComplete

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

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

التحميل

سلوك تحميل الصورة. القيمة الافتراضية هي 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>
  )
}

تعلم المزيد

غير مُحسَّن

عند تعيينه على true، سيتم تقديم الصورة المصدر كما هي من src دون تغيير الجودة أو الحجم أو التنسيق. القيمة الافتراضية هي false.

هذا مفيد للصور التي لا تستفيد من التحسين مثل الصور الصغيرة (أقل من 1 كيلوبايت)، أو الصور المتجهة (SVG)، أو الصور المتحركة (GIF).

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. استخدم أحجام الأجهزة بدلاً من ذلك.
ref. استخدم onLoadingComplete بدلاً من ذلك.
decoding. دائمًا ما تكون "async".

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

أنماط بعيدة

لحماية تطبيقك من المستخدمين الضارين، يلزم التكوين لاستخدام الصور الخارجية. هذا يضمن أن الصور الخارجية من حسابك فقط هي التي يمكن تقديمها من واجهة برمجة تطبيقات تحسين الصور في 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.

النطاقات

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

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

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

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

next.config.js

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

تكوين المحمل

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

next.config.js

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' استخدم مزود سحابي مخصص عن طريق تنفيذ خاصية loader في مكون next/legacy/image

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

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

متقدم

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

أحجام الأجهزة

إذا كنت تعرف عرض الأجهزة المتوقع لمستخدميك، يمكنك تحديد قائمة بنقاط التوقف لعرض الجهاز باستخدام خاصية 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],
  },
}

أحجام الصور

يمكنك تحديد قائمة بعروض الصور باستخدام خاصية 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],
  },
}

التنسيقات المقبولة

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

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

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

next.config.js

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

يمكنك تمكين دعم AVIF، والذي سيعود إلى التنسيق الأصلي لصورة src إذا كان المتصفح لا يدعم AVIF:

next.config.js

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

معلومة مفيدة:

لا نزال نوصي باستخدام WebP لمعظم حالات الاستخدام.

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

إذا كنت تستضيف بنفسك مع Proxy/CDN أمام Next.js، فيجب عليك تكوين الوكيل لإعادة توجيه رأس Accept.

سلوك التخزين المؤقت

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

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

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

الحد الأدنى لوقت التخزين المؤقت

يمكنك تكوين وقت البقاء (TTL) بالثواني للصور المحسنة المخزنة مؤقتًا. في كثير من الحالات، من الأفضل استخدام استيراد صورة ثابت والذي سيقوم تلقائيًا بتجزئة محتويات الملف وتخزين الصورة مؤقتًا إلى الأبد مع رأس 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 لتعيين رأس Cache-Control على الصورة الأساسية (مثل /some-asset.jpg، وليس /_next/image نفسها).

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

تعطيل الاستيراد الثابت

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

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

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

next.config.js

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

السماح بـ 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 لمنع تنفيذ البرامج النصية المضمنة في الصورة.

`contentDispositionType`

يضبط المحمل الافتراضي رأس Content-Disposition على attachment للحماية الإضافية حيث يمكن لواجهة برمجة التطبيقات تقديم صور بعيدة عشوائية.

القيمة الافتراضية هي attachment مما يجبر المتصفح على تنزيل الصورة عند الزيارة مباشرة. هذا مهم بشكل خاص عندما يكون dangerouslyAllowSVG صحيحًا.

يمكنك تكوين inline اختياريًا للسماح للمتصفح بعرض الصورة عند الزيارة مباشرة، دون تنزيلها.

next.config.js

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

الصور المتحركة

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

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

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

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

الصورة (الإصدار القديم)

On this page