Hibrid Next.js-webhelyek üzembe helyezése az Azure Static Web Appsben (előzetes verzió)

Ebben az oktatóanyagban megismerheti, hogyan helyezhet üzembe egy Next.js webhelyet az Azure Static Web Appsben Next.js olyan funkciók támogatásával, mint a React Server Components, a Kiszolgálóoldali renderelés (SSR) és az API-útvonalak.

Előfeltételek

Nem támogatott funkciók előzetes verzióban

A Static Web Apps alábbi funkciói nem támogatottak a hibrid rendereléssel Next.js:

• Válassza ki az Azure-szolgáltatásokat: Társított API-k az Azure Functions, a Azure-alkalmazás Service, az Azure Container Apps vagy az Azure API Management használatával.
• SWA CLI-funkciók: SWA CLI helyi emuláció és üzembe helyezés.
• Részleges funkciók támogatása: A fájl alábbi tulajdonságai staticwebapp.config.json nem támogatottak:
  • A navigációs tartalék nem támogatott.
  • Az átírásokat az Next.js alkalmazáson belüli útvonalakra kell konfigurálni a következőn belül next.config.js: .
  • A fájlon belüli staticwebapp.config.json konfiguráció elsőbbséget élvez a fájlon belüli next.config.jskonfigurációval szemben.
  • A Next.js hely konfigurációját a teljes funkciókompatibilitás érdekében next.config.js kell kezelni.
• Build kihagyása: Ha Next.js alkalmazások skip_api_build=trueesetében a Static Web Apps nem távolítja el a fejlesztői függőségeket, vagy alapértelmezés szerint hozzáadja az éles csomagot. Ha ezeket az optimalizálásokat szeretné, adja hozzá őket az egyéni buildelési lépésekhez, mielőtt továbblép.skip_app_build=true
• Növekményes statikus regeneráció (ISR):: A kép gyorsítótárazása nem támogatott.

Adattár létrehozása

Ez a cikk egy GitHub-sablontárházat használ, hogy megkönnyítse az első lépéseket. A sablon tartalmaz egy kezdőalkalmazást, amely üzembe helyezhető az Azure Static Web Appsben.

1. Új adattár létrehozásához lépjen a következő helyre.

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

2. Az adattár elnevezése a saját első-static-web-appomnak

3. Válassza az Adattár létrehozása sablonból lehetőséget.

   

Statikus webalkalmazás létrehozása

Az adattár létrehozása után létrehozhat egy statikus webalkalmazást az Azure Portalon.

1. Nyissa meg az Azure Portalt.
2. Válassza az Erőforrás létrehozása lehetőséget.
3. Statikus webalkalmazások keresése.
4. Válassza a Static Web Apps elemet.
5. Válassza a Létrehozás lehetőséget.

Az Alapszintű szakaszban először konfigurálja az új alkalmazást, és csatolja egy GitHub-adattárhoz.

Válassza a Bejelentkezés a GitHubbal lehetőséget, és hitelesítés a GitHubbal.

Miután bejelentkezett a GitHubbal, adja meg az adattár adatait.

A Build Details (Összeállítás részletei) szakaszban adja hozzá az előnyben részesített előtér-keretrendszerre vonatkozó konfigurációs adatokat.

1. Válassza Next.js a Build Presets legördülő listában.

2. Tartsa meg az alapértelmezett értéket az Alkalmazás helye mezőben.

3. Hagyja üresen az Api-hely mezőt.

4. Hagyja üresen a Kimeneti hely mezőt.

Válassza az Áttekintés + létrehozás lehetőséget.

A webhely megtekintése

A statikus alkalmazások üzembe helyezésének két aspektusa van. Az első létrehozza az alkalmazást alkotó mögöttes Azure-erőforrásokat. A második egy munkafolyamat, amely létrehozza és közzéteszi az alkalmazást.

Mielőtt megnyithatja az új statikus helyet, az üzembe helyezési buildnek először futnia kell.

A Static Web Apps Overview (Statikus webalkalmazások áttekintése) ablak hivatkozássorozatot jelenít meg, amelyek segítenek a webalkalmazással való interakcióban.

A megjelenő szalagcímre kattintva a GitHub Actions-futtatások állapotának ellenőrzéséhez válassza ki az adattáron futó GitHub Actions-műveleteket. Ha meggyőződik arról, hogy az üzembe helyezési feladat befejeződött, a létrehozott URL-címen keresztül megnyithatja a webhelyét.

A GitHub Actions munkafolyamatának befejezése után az URL-hivatkozást választva megnyithatja a webhelyet az új lapon.

A Next.js projekt helyi beállítása módosítások elvégzéséhez

1. Klónozza az új adattárat a gépére. Mindenképpen cserélje le <a GITHUB_ACCOUNT_NAME> a fiók nevére.

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

2. Nyissa meg a projektet a Visual Studio Code-ban vagy az előnyben részesített kódszerkesztőben.

Kiszolgálóoldali renderelés beállítása

A felügyelt háttérrendszer automatikusan elérhető minden hibrid Next.js üzembe helyezéshez az összes csomagban. A teljesítmény finomhangolásával azonban jobban szabályozhatja a háttérrendszert, ha egyéni háttérrendszert rendel a webhelyhez. Ha egy felügyelt háttérrendszerről csatolt háttérrendszerre vált, a webhely nem tapasztal állásidőt.

Saját háttérrendszer használata

A háttérrendszer létrehozásakor javíthatja a teljesítményt, és jobban szabályozhatja a Next.js kiszolgálóoldali renderelést. Az alábbi lépésekkel egyéni háttérrendszert állíthat be a webhelyéhez.

Az alábbi lépések bemutatják, hogyan társíthat egyéni háttérrendszert a Standard csomaghoz és a statikus webalkalmazások fölé.

1. Nyissa meg a statikus webalkalmazást az Azure Portalon.

2. Válassza a Beállítások, majd az API-k lehetőséget az oldalsó menüben.

3. Válassza a Csatolt háttérrendszer konfigurálása lehetőséget.

4. Hozzon létre egy új App Service-csomagot, vagy válasszon ki egy meglévő App Service-csomagot.

   A kiválasztott App Service-csomagnak legalább S1 termékváltozatot kell használnia.

5. Kattintson a Hivatkozás gombra.

Kiszolgálói renderelt adatok hozzáadása kiszolgálóösszetevővel

Ha kiszolgáló által renderelt adatokat szeretne hozzáadni Next.js projektjéhez az App Router használatával, szerkeszthet egy Next.js összetevőt, hogy kiszolgálóoldali műveletet adjon hozzá az összetevőben lévő adatok megjelenítéséhez. Alapértelmezés szerint Next.js összetevők kiszolgálói renderelhető kiszolgálóösszetevők .

1. Nyissa meg a app/page.tsx fájlt, és adjon hozzá egy olyan műveletet, amely beállítja egy kiszolgálóoldali számítási változó értékét. Ilyenek például az adatok beolvasása vagy más kiszolgálói műveletek.

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

2. Importálja unstable_noStore és next/cache hívja meg az Home összetevőn belül, hogy az útvonal dinamikusan renderelt legyen.

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

   Feljegyzés

   Ez a példa az összetevő dinamikus renderelését kényszeríti a kiszolgáló aktuális idejének kiszolgálómegjelenítésének bemutatására. A Next.js alkalmazás útválasztó-modellje egyéni adatkérések gyorsítótárazását javasolja a Next.js-alkalmazás teljesítményének optimalizálása érdekében. További információ az adatbeolvasásról és a gyorsítótárazásról a Next.js.

3. Frissítse az összetevőt az Home app/pages.tsx fájlban a kiszolgálóoldali adatok megjelenítéséhez.

   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>
       );
   }
   

API-útvonal hozzáadása

A kiszolgálóösszetevők mellett a Next.js útvonalkezelőket is biztosít, amellyel API-útvonalakat hozhat létre a Next.js alkalmazáshoz. Ezeket az API-kat lekérheti az ügyfélösszetevőkben.

Először adjon hozzá egy API-útvonalat.

1. Hozzon létre egy új fájlt a címen app/api/currentTime/route.tsx. Ez a fájl tartalmazza az új API-végpont Útvonalkezelőt.

2. Adjon hozzá egy kezelőfüggvényt, amely adatokat ad vissza az API-ból.

   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. Hozzon létre egy új fájlt a címen app/components/CurrentTimeFromAPI.tsx. Ez az összetevő létrehoz egy tárolót az ügyfélösszetevő számára, amely lekéri az API-t a böngészőből.

4. Adjon hozzá egy ügyfélösszetevőt, amely lekéri az API-t ebben a fájlban.

   '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>
       )
   }
   

Ez az ügyfélösszetevő egy useEffect React-kampóval lekéri az API-t, hogy a terhelés befejezése után renderelje az összetevőt. Az 'use client' irányelv ezt az elemet ügyfélösszetevőként azonosítja. További információ: Ügyfélösszetevők.

1. Szerkessze az app/page.tsx parancsot az CurrentTimeFromAPI ügyfélösszetevő importálásához és rendereléséhez.

   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. Az API-útvonal eredménye megjelenik az oldalon.

A futtatókörnyezet verziójának konfigurálása Next.js

Bizonyos Next.js verziókhoz meghatározott Node.js verziók szükségesek. Egy adott csomópontverzió konfigurálásához beállíthatja a engines fájl tulajdonságát package.json egy verzió kijelölésére.

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

Környezeti változók beállítása Next.js

Next.js környezeti változókat használ a létrehozáskor és kérésre, a statikus oldallétrehozás és a dinamikus oldallétrehozás kiszolgálóoldali rendereléssel történő támogatásához. Ezért állítsa be a környezeti változókat a buildelési és üzembe helyezési feladatban, valamint az Azure Static Web Apps-erőforrás környezeti változóiban .

...
      - 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 }}
...

Önálló funkció engedélyezése

Ha az alkalmazás mérete meghaladja a 250 MB-ot, a Next.js Kimeneti fájlkövetés funkció segít optimalizálni az alkalmazás méretét és növelni a teljesítményt.

A kimeneti fájlkövetés a teljes alkalmazás tömörített verzióját hozza létre a szükséges csomagfüggőségekkel. Ez a csomag egy .next/standalone nevű mappába van beépítve. Ezzel a csomaggal az alkalmazás önállóan is üzembe helyezhető node_modules függőségek nélkül.

A funkció engedélyezéséhez standalone adja hozzá a következő tulajdonságot a következőhöz next.config.js:

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

Ezután konfigurálja a buildpackage.json fájl parancsát, hogy statikus fájlokat másoljon az önálló kimenetre.

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

Útválasztás és köztes szoftver konfigurálása üzembe helyezéshez

Az útvonalak Next.js projektleíróját egyéni átirányításokkal, átírásokkal és köztes szoftverekkel konfigurálhatja. Ezeket a kezelőket gyakran használják hitelesítéshez, személyre szabáshoz, útválasztáshoz és nemzetköziesítéshez. Az egyéni kezelés hatással van a Next.js webhely alapértelmezett útválasztására, és a konfigurációnak kompatibilisnek kell lennie a statikus webalkalmazások üzemeltetésével.

A Static Web Apps ellenőrzi, hogy a Next.js webhely sikeresen üzembe lett-e helyezve, ha a létrehozáskor hozzáad egy lapot a webhelyhez. A lap neve el van nevezve public/.swa/health.html, a Static Web Apps pedig egy sikeres válasz navigálásával /.swa/health.html és ellenőrzésével ellenőrzi a webhely sikeres indítását és üzembe helyezését. A köztes szoftver és az egyéni útválasztás, amely átirányításokat és átírásokat is tartalmaz, hatással lehet az elérési út elérésére, ami megakadályozhatja a /.swa/health.html Static Web Apps üzembe helyezésének érvényesítését. A köztes szoftver és az útválasztás statikus webalkalmazásokba való sikeres üzembe helyezéshez való konfigurálásához kövesse az alábbi lépéseket:

1. Zárja ki az útvonalakat a middleware.ts köztes szoftver konfigurációjában lévő (vagy .js) fájlból kiindulva.swa.

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

2. Konfigurálja az átirányításokat, next.config.js hogy kizárja az útvonalakat a következővel .swakezdődően: .

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

3. Konfigurálja az újraírási szabályokat next.config.js , hogy kizárja az útvonalakat a következővel .swakezdődően: .

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

Ezek a kódrészletek kizárják azokat az útvonalakat, amelyek az egyéni útválasztás vagy köztes szoftver feldolgozásának leállításához .swa kezdődnek. Ezek a szabályok biztosítják, hogy az útvonalak a várt módon oldódhassanak fel az üzembe helyezés ellenőrzése során.

Naplózás engedélyezése Next.js

A Next.js kiszolgálói API hibaelhárításával kapcsolatos ajánlott eljárásokat követve adjon hozzá naplózást az API-hoz a hibák elhárításához. Az Azure-ra való naplózás az Application Insightst használja. Az SDK előzetes betöltéséhez létre kell hoznia egy egyéni indítási szkriptet. További tudnivalók:

• Példa az Application Insights + Next.js preload szkriptre
• GitHub-probléma
• Előzetes betöltés Next.js

Az erőforrások eltávolítása

Ha nem folytatja az alkalmazás használatát, az alábbi lépések végrehajtásával törölheti az Azure Static Web Apps-példányt:

1. Nyissa meg az Azure Portalt.
2. Keressen rá az első web-static-appomra a felső keresősávon.
3. Válassza ki az alkalmazás nevét.
4. Válassza a Törlés lehetőséget.
5. Válassza az Igen lehetőséget a törlési művelet megerősítéséhez (a művelet végrehajtása eltarthat néhány percig).

Következő lépések