getServerSideProps

إذا قمت بتصدير دالة تسمى getServerSideProps (العرض من جانب الخادم - SSR) من صفحة، فإن Next.js سيقوم بتهيئة عرض هذه الصفحة مسبقًا عند كل طلب باستخدام البيانات التي تُرجعها getServerSideProps.

import type { InferGetServerSidePropsType, GetServerSideProps } from 'next'

type Repo = {
  name: string
  stargazers_count: number
}

export const getServerSideProps = (async (context) => {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}) satisfies GetServerSideProps<{
  repo: Repo
}>

export default function Page({
  repo,
}: InferGetServerSidePropsType<typeof getServerSideProps>) {
  return repo.stargazers_count
}

export async function getServerSideProps() {
  const res = await fetch('https://api.github.com/repos/vercel/next.js')
  const repo = await res.json()
  return { props: { repo } }
}

export default function Page({ repo }) {
  return repo.stargazers_count
}

لاحظ أنه بغض النظر عن نوع العرض، أي props سيتم تمريرها إلى مكون الصفحة ويمكن رؤيتها على جانب العميل في HTML الأولي. هذا للسماح للصفحة بأن يتم ترطيبها (hydrate) بشكل صحيح. تأكد من عدم تمرير أي معلومات حساسة لا يجب أن تكون متاحة على العميل في props.

متى يتم تشغيل getServerSideProps

getServerSideProps يعمل فقط على جانب الخادم ولا يعمل أبدًا في المتصفح. إذا كانت الصفحة تستخدم getServerSideProps، فإن:

• عند طلب هذه الصفحة مباشرة، يعمل getServerSideProps وقت الطلب، وسيتم تهيئة عرض هذه الصفحة مسبقًا مع الـ props المُرجعة
• عند طلب هذه الصفحة على انتقالات الصفحة من جانب العميل عبر next/link أو next/router، يرسل Next.js طلب API إلى الخادم، الذي يقوم بتشغيل getServerSideProps

getServerSideProps يُرجع JSON الذي سيتم استخدامه لعرض الصفحة. كل هذا العمل سيتم التعامل معه تلقائيًا بواسطة Next.js، لذلك لا تحتاج إلى فعل أي شيء إضافي طالما أن لديك getServerSideProps مُعرّفًا.

يمكنك استخدام أداة إزالة الكود في Next.js للتحقق مما يزيله Next.js من حزمة جانب العميل.

getServerSideProps يمكن تصديره فقط من صفحة. لا يمكنك تصديره من ملفات غير الصفحات.

لاحظ أنه يجب عليك تصدير getServerSideProps كدالة مستقلة - لن تعمل إذا أضفت getServerSideProps كخاصية لمكون الصفحة.

مرجع واجهة برمجة التطبيقات لـ getServerSideProps يغطي جميع المعلمات والـ props التي يمكن استخدامها مع getServerSideProps.

متى يجب استخدام getServerSideProps

يجب استخدام getServerSideProps فقط إذا كنت بحاجة إلى عرض صفحة يجب جلب بياناتها عند وقت الطلب. قد يكون هذا بسبب طبيعة البيانات أو خصائص الطلب (مثل رؤوس authorization أو الموقع الجغرافي). الصفحات التي تستخدم getServerSideProps سيتم عرضها من جانب الخادم عند وقت الطلب وسيتم تخزينها مؤقتًا فقط إذا تم تكوين رؤوس cache-control.

إذا لم تكن بحاجة إلى عرض البيانات أثناء الطلب، فيجب أن تفكر في جلب البيانات على جانب العميل أو استخدام getStaticProps.

getServerSideProps أو مسارات API

قد يكون من المغري اللجوء إلى مسار API عندما تريد جلب البيانات من الخادم، ثم استدعاء مسار API هذا من getServerSideProps. هذا نهج غير ضروري وغير فعال، لأنه سيؤدي إلى طلب إضافي بسبب تشغيل كل من getServerSideProps ومسارات API على الخادم.

خذ المثال التالي. يتم استخدام مسار API لجلب بعض البيانات من نظام إدارة المحتوى (CMS). ثم يتم استدعاء مسار API هذا مباشرة من getServerSideProps. هذا ينتج عنه استدعاء إضافي، مما يقلل الأداء. بدلاً من ذلك، استورد المنطق المستخدم داخل مسار API مباشرة إلى getServerSideProps. قد يعني هذا استدعاء نظام إدارة المحتوى أو قاعدة البيانات أو واجهة برمجة تطبيقات أخرى مباشرة من داخل getServerSideProps.

getServerSideProps مع مسارات Edge API

يمكن استخدام getServerSideProps مع كل من وظائف الخادم بدون خادم (Serverless) و Edge، ويمكنك تعيين الـ props في كليهما. ومع ذلك، حاليًا في بيئة Edge، ليس لديك حق الوصول إلى كائن الاستجابة. هذا يعني أنه لا يمكنك - على سبيل المثال - إضافة ملفات تعريف الارتباط (cookies) في getServerSideProps. للحصول على حق الوصول إلى كائن الاستجابة، يجب الاستمرار في استخدام بيئة Node.js، وهي البيئة الافتراضية.

يمكنك تعيين البيئة بشكل صريح لكل صفحة عن طريق تعديل config، على سبيل المثال:

export const config = {
  runtime: 'nodejs', // أو "edge"
}

export const getServerSideProps = async () => {}

جلب البيانات على جانب العميل

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

• أولاً، اعرض الصفحة فورًا بدون بيانات. يمكن عرض أجزاء من الصفحة مسبقًا باستخدام التوليد الثابت. يمكنك عرض حالات التحميل للبيانات المفقودة
• ثم، جلب البيانات على جانب العميل وعرضها عندما تكون جاهزة

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

استخدام getServerSideProps لجلب البيانات عند وقت الطلب

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

// يتم استدعاء هذا عند كل طلب
export async function getServerSideProps() {
  // جلب البيانات من واجهة برمجة التطبيقات الخارجية
  const res = await fetch(`https://.../data`)
  const data = await res.json()

  // تمرير البيانات إلى الصفحة عبر props
  return { props: { data } }
}

export default function Page({ data }) {
  // عرض البيانات...
}

التخزين المؤقت مع العرض من جانب الخادم (SSR)

يمكنك استخدام رؤوس التخزين المؤقت (Cache-Control) داخل getServerSideProps لتخزين الاستجابات الديناميكية مؤقتًا. على سبيل المثال، باستخدام stale-while-revalidate.

// تعتبر هذه القيمة طازجة لمدة عشر ثوانٍ (s-maxage=10).
// إذا تم تكرار الطلب خلال الثواني العشر التالية، ستظل القيمة المخزنة مؤقتًا طازجة. إذا تم تكرار الطلب قبل 59 ثانية،
// ستكون القيمة المخزنة مؤقتًا قديمة ولكن سيتم عرضها (stale-while-revalidate=59).
//
// في الخلفية، سيتم إجراء طلب إعادة تحقق لتعبئة التخزين المؤقت
// بقيمة طازجة. إذا قمت بتحديث الصفحة، سترى القيمة الجديدة.
export async function getServerSideProps({ req, res }) {
  res.setHeader(
    'Cache-Control',
    'public, s-maxage=10, stale-while-revalidate=59'
  )

  return {
    props: {},
  }
}

تعلم المزيد عن التخزين المؤقت.

هل يعرض getServerSideProps صفحة خطأ

إذا تم طرح خطأ داخل getServerSideProps، فسيتم عرض ملف pages/500.js. تحقق من الوثائق الخاصة بـ صفحة 500 لمعرفة المزيد حول كيفية إنشائها. أثناء التطوير، لن يتم استخدام هذا الملف وسيتم عرض شاشة خطأ التطوير بدلاً من ذلك.