نشر مواقع Next.js المختلطة على Azure Static Web Apps (معاينة)

في هذا البرنامج التعليمي، ستتعلم كيفية نشر موقع ويب Next.js على Azure Static Web Apps، باستخدام دعم ميزات Next.js مثل React Server Components وServer-side Rendering (SSR) ومسارات API.

المتطلبات الأساسية

الميزات غير المعتمدة في المعاينة

الميزات التالية لتطبيقات الويب الثابتة غير مدعومة Next.js مع العرض المختلط:

• حدد خدمات Azure: واجهات برمجة التطبيقات المرتبطة باستخدام Azure Functions أو Azure App Service أو Azure Container Apps أو Azure API Management.
• ميزات SWA CLI: المحاكاة المحلية ل SWA CLI ونشرها.
• دعم الميزات الجزئية: الخصائص التالية في staticwebapp.config.json الملف غير مدعومة:
  • لا يتم دعم التنقل الاحتياطي.
  • يجب تكوين عمليات إعادة كتابة التوجيه إلى المسارات داخل تطبيق Next.js داخل next.config.js.
  • التكوين داخل staticwebapp.config.json الملف له الأسبقية على التكوين داخل next.config.js.
  • يجب معالجة تكوين موقع Next.js باستخدام next.config.js لتوافق الميزات الكاملة.
• تخطي البنية: بالنسبة للتطبيقات Next.js إذا لم skip_api_build=trueتقم تطبيقات الويب الثابتة بإزالة تبعيات التطوير أو إضافة الحزمة الحادة بشكل افتراضي. إذا كنت تريد هذه التحسينات، أضفها إلى خطوات الإنشاء المخصصة قبل تمرير skip_app_build=true.
• إعادة إنشاء ثابتة تزايدية (ISR):التخزين المؤقت للصور غير مدعوم.

إنشاء مستودع

تستخدم هذه المقالة مستودع قالب GitHub لتسهيل بدء التشغيل. يتميز القالب بتطبيق بدء التشغيل لنشره في Azure Static Web Apps.

1. انتقل إلى الموقع التالي لإنشاء مستودع جديد.

   https://github.com/staticwebdev/nextjs-hybrid-starter/generate

2. قم بتسمية مستودعك باسم my-first-static-web-app

3. حدد «Create repository from template».

   

إنشاء تطبيق ويب ثابت

الآن بعد إنشاء المستودع، يمكنك إنشاء تطبيق ويب ثابت من مدخل Azure.

1. انتقل إلى مدخل Azure.
2. حدد Create a Resource.
3. البحث عن Static Web Apps.
4. حدد "Static Web Apps".
5. حدد إنشاء.

في قسم Basics ، ابدأ بتكوين تطبيقك الجديد وربطه بمستودع GitHub.

حدد تسجيل الدخول باستخدام GitHub وصادق باستخدام GitHub.

بعد تسجيل الدخول باستخدام GitHub، أدخل معلومات المستودع.

في قسم Build Details ، أضف تفاصيل التكوين الخاصة لإطار عمل الواجهة الأمامية المفضل لديك.

1. حدد Next.js من القائمة المنسدلة Build Presets .

2. احتفظ بالقيمة الافتراضية في مربع موقع التطبيق.

3. اترك مربع Api location فارغًا.

4. اترك مربع موقع الإخراج فارغا.

حدد "Review + create".

عرض الموقع الإلكتروني

هناك جانبان لنشر تطبيق ثابت. يقوم الأول بإنشاء موارد Azure الأساسية التي تشكل تطبيقك. والثاني هو سير عمل يقوم بإنشاء ونشر التطبيق الخاص بك.

قبل أن تتمكن من الانتقال إلى موقعك الثابت الجديد، يجب أن ينتهي إنشاء النشر أولا من التشغيل.

تعرض نافذة Static Web Apps Overview سلسلة من الارتباطات التي تساعدك على التفاعل مع تطبيق الويب الخاص بك.

يؤدي التحديد على الشعار الذي يقول ، حدد هنا للتحقق من حالة عمليات تشغيل GitHub Actions الخاصة بك إلى إجراءات GitHub التي تعمل مقابل المستودع الخاص بك. بمجرد التحقق من اكتمال مهمة النشر، يمكنك الانتقال إلى موقع الويب الخاص بك عبر عنوان URL الذي تم إنشاؤه.

بمجرد اكتمال سير عمل الإجراءات GitHub، يمكنك تحديد رابط URL لفتح موقع الويب في علامة تبويب جديدة.

إعداد مشروع Next.js محليا لإجراء تغييرات

1. استنساخ المستودع الجديد إلى جهازك. تأكد من استبدال <GITHUB_ACCOUNT_NAME> باسم حسابك.

   git clone http://github.com/<GITHUB_ACCOUNT_NAME>/my-first-static-web-app
   

2. افتح المشروع في Visual Studio Code أو محرر التعليمات البرمجية المفضل لديك.

إعداد العرض من جانب الخادم

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

إحضار الواجهة الخلفية الخاصة بك

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

توضح لك الخطوات التالية كيفية إقران خلفية مخصصة بخطتك القياسية وتطبيقات الويب الثابتة أعلاه.

1. انتقل إلى تطبيق الويب الثابت في مدخل Microsoft Azure.

2. حدد الإعدادات ثم واجهات برمجة التطبيقات من القائمة الجانبية.

3. حدد تكوين الواجهة الخلفية المرتبطة.

4. إما إنشاء خطة App Service جديدة أو تحديد خطة App Service موجودة.

   يجب أن تستخدم خطة خدمة التطبيقات المحددة S1 SKU على الأقل.

5. انقر فوق ارتباط.

إضافة بيانات تم عرضها بواسطة الخادم باستخدام مكون الخادم

لإضافة البيانات التي يعرضها الخادم في مشروع Next.js الخاص بك باستخدام App Router، قم بتحرير مكون Next.js لإضافة عملية من جانب الخادم لعرض البيانات في المكون. بشكل افتراضي، Next.js المكونات هي مكونات الخادم التي يمكن عرضها من قبل الخادم.

1. app/page.tsx افتح الملف وأضف عملية تعين قيمة متغير حوسب من جانب الخادم. تتضمن الأمثلة إحضار البيانات أو عمليات الخادم الأخرى.

   export default function Home() {
       const timeOnServer = new Date().toLocaleTimeString('en-US');
       return(
           ...
       );
   }
   

2. قم بالاستيراد unstable_noStore من next/cache واستدعائه داخل Home المكون لضمان عرض المسار ديناميكيا.

   import { unstable_noStore as noStore } from 'next/cache';
   
   export default function Home() {
       noStore();
   
       const timeOnServer = new Date().toLocaleTimeString('en-US');
       return(
           ...
       );
   }
   

   إشعار

   يفرض هذا المثال العرض الديناميكي لهذا المكون لإظهار عرض الخادم للوقت الحالي للخادم. يوصي نموذج App Router Next.js بالتخزين المؤقت لطلبات البيانات الفردية لتحسين أداء تطبيق Next.js. اقرأ المزيد حول إحضار البيانات والتخزين المؤقت في Next.js.

3. Home تحديث المكون في app/pages.tsx لعرض البيانات من جانب الخادم.

   import { unstable_noStore as noStore } from 'next/cache';
   
   export default function Home() {
       noStore();
   
       const timeOnServer = new Date().toLocaleTimeString('en-US');
       return(
           <main className="flex min-h-screen flex-col items-center justify-between p-24">
               <div>
                   This is a Next.js application hosted on Azure Static Web Apps with hybrid rendering. The time on the server is <strong>{timeOnServer}</strong>.
               </div>
           </main>
       );
   }
   

إضافة مسار واجهة برمجة التطبيقات

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

ابدأ بإضافة مسار API.

1. إنشاء ملف جديد في app/api/currentTime/route.tsx. يحتوي هذا الملف على معالج التوجيه لنقطة نهاية واجهة برمجة التطبيقات الجديدة.

2. أضف دالة معالج لإرجاع البيانات من واجهة برمجة التطبيقات.

   import { NextResponse } from 'next/server';
   
   export const dynamic = 'force-dynamic';
   
   export async function GET() { 
       const currentTime = new Date().toLocaleTimeString('en-US');
   
       return NextResponse.json({ 
           message: `Hello from the API! The current time is ${currentTime}.`
       });
   }
   

3. إنشاء ملف جديد في app/components/CurrentTimeFromAPI.tsx. ينشئ هذا المكون حاوية لمكون العميل الذي يجلب واجهة برمجة التطبيقات من المتصفح.

4. أضف مكون عميل يجلب واجهة برمجة التطبيقات في هذا الملف.

   'use client';
   
   import { useEffect, useState } from 'react';
   
   export function CurrentTimeFromAPI(){
       const [apiResponse, setApiResponse] = useState('');
       const [loading, setLoading] = useState(true);
   
       useEffect(() => {
           fetch('/api/currentTime')
               .then((res) => res.json())
               .then((data) => {
               setApiResponse(data.message);
               setLoading(false);
               });
           }, 
       []);
   
       return (
           <div className='pt-4'>
               The message from the API is: <strong>{apiResponse}</strong>
           </div>
       )
   }
   

يجلب مكون العميل هذا واجهة برمجة التطبيقات مع useEffect خطاف React لعرض المكون بعد اكتمال التحميل. 'use client' يعرف التوجيه هذا العنصر على أنه مكون عميل. لمزيد من المعلومات، راجع مكونات العميل.

1. تحرير app/page.tsx لاستيراد وعرض CurrentTimeFromAPI مكون العميل.

   import { unstable_noStore as noStore } from 'next/cache';
   import { CurrentTimeFromAPI } from './components/CurrentTimeFromAPI';
   
   export default function Home() {
       noStore();
   
       const timeOnServer = new Date().toLocaleTimeString('en-US');
       return(
           <main className="flex min-h-screen flex-col items-center justify-between p-24">
               <div>
                   This is a Next.js application hosted on Azure Static Web Apps with hybrid rendering. The time on the server is <strong>{timeOnServer}</strong>.
               </div>
               <CurrentTimeFromAPI />
           </main>
       );
   }
   

2. يتم عرض النتيجة من مسار API على الصفحة.

تكوين إصدار وقت التشغيل Next.js

تتطلب بعض إصدارات Next.js إصدارات Node.js محددة. لتكوين إصدار عقدة معين، يمكنك تعيين engines خاصية الملف الخاص بك package.json لتعيين إصدار.

{
  ...
  "engines": {
    "node": "18.17.1"
  }
}

تعيين متغيرات البيئة Next.js

يستخدم Next.js متغيرات البيئة في وقت الإنشاء وفي وقت الطلب، لدعم كل من إنشاء الصفحة الثابتة وإنشاء الصفحة الديناميكية مع العرض من جانب الخادم. لذلك، قم بتعيين متغيرات البيئة داخل مهمة الإنشاء والنشر، وفي متغيرات البيئة لمورد Azure Static Web Apps.

...
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }} # Used for GitHub integrations (i.e. PR comments)
          action: "upload"
          app_location: "/" 
          api_location: ""
          output_location: "" 
        env:
          DB_HOST: ${{ secrets.DB_HOST }}
          DB_USER: ${{ secrets.DB_USER }}
          DB_DATABASE: ${{ secrets.DB_DATABASE }}
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}
          DB_PORT: ${{ secrets.DB_PORT }}
...

تمكين ميزة مستقلة

عندما يتجاوز حجم التطبيق 250 ميغابايت، تساعد ميزة Next.js Output File Tracing في تحسين حجم التطبيق وتحسين الأداء.

يقوم "تتبع ملف الإخراج" بإنشاء إصدار مضغوط من التطبيق بأكمله مع تبعيات الحزمة الضرورية. تم تضمين هذه الحزمة في مجلد يسمى .next/standalone. باستخدام هذه الحزمة، يمكن نشر تطبيقك من تلقاء نفسه دون node_modules التبعيات.

لتمكين الميزة standalone ، أضف الخاصية التالية إلى next.config.js:

module.exports ={
    output:"standalone",
}

بعد ذلك، قم بتكوين build الأمر في package.json الملف لنسخ الملفات الثابتة إلى الإخراج المستقل.

{
  ...
  "scripts": {
    ...
    "build": "next build && cp -r .next/static .next/standalone/.next/ && cp -r public .next/standalone/"
    ...
  }
  ...
}

تكوين التوجيه والبرامج الوسيطة للنشر

يمكنك تكوين مقبض مشروع Next.js للمسارات مع عمليات إعادة التوجيه المخصصة وإعادة الكتابة والبرامج الوسيطة. تستخدم هذه المعالجات بشكل شائع للمصادقة والتخصيص والتوجيه والتدويل. تؤثر المعالجة المخصصة على التوجيه الافتراضي لموقع Next.js ويجب أن يكون التكوين متوافقا مع الاستضافة على Static Web Apps.

تتحقق تطبيقات الويب الثابتة من نشر موقع Next.js بنجاح عن طريق إضافة صفحة إلى موقعك في وقت الإنشاء. تسمى public/.swa/health.htmlالصفحة ، وتتحقق Static Web Apps من بدء تشغيل موقعك ونشره بنجاح عن طريق الانتقال إلى /.swa/health.html استجابة ناجحة والتحقق منها. يمكن أن يؤثر البرنامج الوسيط والتوجيه المخصص، الذي يتضمن عمليات إعادة التوجيه وإعادة الكتابة، على الوصول إلى /.swa/health.html المسار، مما يمكن أن يمنع التحقق من صحة نشر Static Web Apps. لتكوين البرامج الوسيطة والتوجيه للنشر الناجح إلى Static Web Apps، اتبع الخطوات التالية:

1. استبعاد المسارات التي تبدأ في .swamiddleware.ts ملف (أو .js) في تكوين البرنامج الوسيط الخاص بك.

   export const config = {
     matcher: [
       /*
        * Match all request paths except for the ones starting with:
        * - .swa (Azure Static Web Apps)
        */
       '/((?!.swa).*)',
     ],
   }
   

2. قم بتكوين عمليات إعادة التوجيه الخاصة بك في next.config.js لاستبعاد المسارات بدءا من .swa.

   module.exports = {
       async redirects() {
           return [
             {
               source: '/((?!.swa).*)<YOUR MATCHING RULE>',
               destination: '<YOUR REDIRECT RULE>', 
               permanent: false,
             },
           ]
       },
   };
   

3. تكوين قواعد إعادة الكتابة في next.config.js لاستبعاد المسارات بدءا من .swa.

   module.exports = {
       async rewrites() {
           return {
               beforeFiles: [
                   {
                       source: '/((?!.swa).*)<YOUR MATCHING RULE>',
                       destination: '<YOUR REWRITE RULE>', 
                   }
               ]
           }
       },
   };
   

تستبعد قصاصات التعليمات البرمجية هذه المسارات التي تبدأ ب .swa لإيقاف التوجيه المخصص أو البرامج الوسيطة من معالجة هذه الطلبات. تضمن هذه القواعد حل المسارات كما هو متوقع أثناء التحقق من صحة التوزيع.

تمكين التسجيل Next.js

باتباع أفضل الممارسات لاستكشاف أخطاء واجهة برمجة تطبيقات الخادم Next.js وإصلاحها، أضف تسجيل الدخول إلى واجهة برمجة التطبيقات لالتقاط هذه الأخطاء. يستخدم تسجيل الدخول إلى Azure Application Insights. من أجل التحميل المسبق ل SDK هذا، تحتاج إلى إنشاء برنامج نصي مخصص لبدء التشغيل. لمعرفة المزيد:

• مثال على البرنامج النصي للتحميل المسبق ل Application Insights + Next.js
• مشكلة GitHub
• التحميل المسبق مع Next.js

تنظيف الموارد

إذا كنت لن تستمر في استخدام هذا التطبيق، يمكنك حذف مثيل Azure Static Web Apps عن طريق تشغيل الأمر التالي:

1. افتح مدخل Azure.
2. ابحث عن my-first-web-static-app من شريط البحث العلوي.
3. حدد اسم التطبيق
4. حدد حذف.
5. حدد نعم لتأكيد إجراء الحذف (قد يستغرق هذا الإجراء بضع لحظات لإكماله).

الخطوات التالية