مكون <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/**',
      },
    ],
  },
}

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

إليك مثال آخر لخاصية remotePatterns في ملف next.config.js:

next.config.js

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

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

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

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

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

النطاقات (Domains)

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

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

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

إليك مثال لخاصية 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، مما قد يؤدي إلى ثغرات أمنية بدون رؤوس سياسة أمان المحتوى (Content Security Policy (CSP)) المناسبة.

إذا كنت بحاجة إلى تقديم صور 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