نشر مواقع 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 مع اشتراك نشط. أنشئ حساباً مجاناً.
• حساب GitHub. أنشئ حساباً مجاناً.
• Node.JS مثبت.
• تم تثبيت Next.js CLI . راجع دليل بدء Next.js للحصول على التفاصيل.

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

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

• واجهات برمجة التطبيقات المرتبطة باستخدام Azure Functions أو Azure App Service أو Azure Container Apps أو Azure API Management.
• المحاكاة المحلية ل SWA CLI ونشرها.
• دعم جزئي للملف staticwebapp.config.json .
  • لا يتم دعم التنقل الاحتياطي.
  • يجب تكوين عمليات إعادة كتابة التوجيه إلى المسارات داخل تطبيق Next.js داخل next.config.js.
  • التكوين داخل staticwebapp.config.json الملف له الأسبقية على التكوين داخل next.config.js.
  • يجب معالجة تكوين موقع Next.js باستخدام next.config.js لتوافق الميزات الكاملة.
• skip_app_buildskip_api_build ولا يمكن استخدامها داخل Azure/static-web-apps-deploy@v1 صورة التوزيع.
• لا يدعم التجديد الثابت المتزايد (ISR) التخزين المؤقت للصور.

إشعار

الحد الأقصى لحجم التطبيق لتطبيق Next.js المختلط هو 250 ميغابايت. استخدم ميزة مستقلة من خلال Next.js لأحجام التطبيقات المحسنة. إذا لم يكن هذا كافيا، ففكر في استخدام HTML الثابت المصدر Next.js إذا كان متطلبات حجم التطبيق الخاص بك أكثر من 250 ميغابايت.

إنشاء مستودع

تستخدم هذه المقالة مستودع قالب 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.

الإعداد	القيمة‬
الاشتراك	حدد اشتراك Azure الخاص بك.
مجموعة الموارد	حدد الارتباط Create new، وأدخل static-web-apps-test في مربع النص.
الاسم	أدخل my-first-static-web-app في مربع النص.
نوع الخطة	حدد Free.
Azure Functions and staging details	حدد أقرب منطقة إليك.
المصدر	حدد GitHub.

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

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

الإعداد	القيمة‬
المنظمة	حدد مؤسستك.
المستودع	حدد my-first-web-static-app.
فرع	حدد "main".

إشعار

إذا لم تشاهد أي مستودعات:

• قد تحتاج إلى تخويل Azure Static Web Apps في GitHub. استعرض للوصول إلى مستودع GitHub وانتقل إلى الإعدادات Applications > Authorized OAuth Apps، وحدد Azure Static Web Apps، ثم حدد Grant>.
• قد تحتاج إلى تخويل Azure Static Web Apps في مؤسسة Azure DevOps. يجب أن تكون مالكا للمؤسسة لمنح الأذونات. طلب الوصول إلى تطبيق جهة خارجية عبر OAuth. لمزيد من المعلومات، راجع تخويل الوصول إلى واجهات برمجة تطبيقات REST باستخدام OAuth 2.0.

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

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

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

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

4. اترك مربع App artifact location فارغا.

حدد "Review + create".

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

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

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

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

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

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

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

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

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

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

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

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

يقوم 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 والبرامج الوسيطة للنشر إلى Azure Static Web Apps

يمكن تكوين مشروع 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. حدد نعم لتأكيد إجراء الحذف (قد يستغرق هذا الإجراء بضع لحظات لإكماله).

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

تكوين إعدادات التطبيق