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.

Feljegyzés

Next.js hibrid támogatás előzetes verzióban érhető el.

Előfeltételek

• Egy Azure-fiók, aktív előfizetéssel. Fiók ingyenes létrehozása.
• Egy GitHub-fiók. Fiók ingyenes létrehozása.
• Telepített Node.js.
• Next.js parancssori felület telepítve van. A részletekért tekintse meg az Next.js Első lépések útmutatót .

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:

• Társított API-k az Azure Functions, Azure-alkalmazás Szolgáltatás, Az Azure Container Apps vagy az Azure API Management használatával.
• SWA CLI helyi emulációja és üzembe helyezése.
• A fájl részleges támogatása staticwebapp.config.json .
  • 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.
• skip_app_build és skip_api_build nem használható az üzembe helyezési lemezképen Azure/static-web-apps-deploy@v1 belül.
• A növekményes statikus regeneráció (ISR) nem támogatja a képek gyorsítótárazását.

Feljegyzés

A hibrid Next.js alkalmazás maximális mérete 250 MB. Használjon különálló funkciót Next.js optimalizált alkalmazásméretekhez. Ha ez nem elegendő, fontolja meg a statikus HTML exportált Next.js használatát, ha az alkalmazásméretre vonatkozó követelmény meghaladja a 250 MB-ot.

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.

Beállítás	Érték
Előfizetés	Válassza ki az Azure-előfizetését.
Erőforráscsoport	Válassza az Új hivatkozás létrehozása lehetőséget, és írja be a static-web-apps-test kifejezést a szövegmezőbe.
Név	Írja be a my-first-static-web-appot a szövegmezőbe.
Konstrukció típusa	Válassza az Ingyenes lehetőséget.
Az Azure Functions és az előkészítés részletei	Válasszon ki egy Önhöz legközelebbi régiót.
Forrás	Válassza a GitHub lehetőséget.

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.

Beállítás	Érték
Organization	Válassza ki a szervezetet.
Adattár	Válassza ki az első web-static-appot.
Ág	Válassza ki a fő elemet.

Feljegyzés

Ha nem lát adattárakat:

• Előfordulhat, hogy engedélyeznie kell az Azure Static Web Appst a GitHubon. Keresse meg a GitHub-adattárat, és nyissa meg Gépház > Alkalmazások > engedélyezett OAuth-alkalmazásait, válassza az Azure Static Web Apps lehetőséget, majd válassza a Grant lehetőséget.
• Előfordulhat, hogy engedélyeznie kell az Azure Static Web Appst az Azure DevOps-szervezetben. Az engedélyek megadásához a szervezet tulajdonosának kell lennie. Külső alkalmazáshozzáférés kérése az OAuthon keresztül. További információ: REST API-k hozzáférésének engedélyezése az OAuth 2.0-val.

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 az alkalmazásösszetevő helyének mezőjé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 YOUR_GITHUB_ACCOUNT_NAME> a fiók nevére.

   git clone http://github.com/<YOUR_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ói renderelt adatok hozzáadása kiszolgálóösszetevővel

Ha kiszolgáló által renderelt adatokat szeretne hozzáadni a Next.js projekthez az App Router használatával, szerkeszthet egy Next.js összetevőt, hogy kiszolgálóoldali műveleteket 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 a kiszolgálóoldali számítású 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. Ezek az API-k lekérhetők 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 fájl "motorok" tulajdonságát package.json úgy, hogy egy verziót jelöljön ki.

{
  ...
  "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 .next/standalone nevű mappába beépített szükséges csomagfüggőségekkel. Ez a mappa önállóan, további node_modules függőségek nélkül telepíthető.

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

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

A statikus fájlok önálló kimenetbe másolásához konfigurálnia build kell a package.json fájlban található parancsot is.

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

A Next.js útválasztás és köztes szoftver konfigurálása az Azure Static Web Appsben való üzembe helyezéshez

A Next.js projekt úgy konfigurálható, hogy átirányításokkal, átírásokkal és köztes szoftverekkel egyénileg kezelje az útvonalakat. 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. Az átirányítások next.config.js konfigurálása az útvonalak kizárásához a következővel kezdődően: .swa

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

3. Konfigurálja az újraírásokat next.config.js az útvonalak kizárásához a következővel kezdődően: .swa

   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ással vagy köztes szoftverrel .swa való kezelésből indulnak ki. 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 alkalmazás Elemzések használ. 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 Elemzések + 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

Alkalmazásbeállítások konfigurálása