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ülinext.config.js
konfigurá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
ésskip_api_build
nem használható az üzembe helyezési lemezképenAzure/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.
Új adattár létrehozásához lépjen a következő helyre.
https://github.com/staticwebdev/nextjs-hybrid-starter/generate
Az adattár elnevezése a saját első-static-web-appomnak
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.
- Nyissa meg az Azure Portalt.
- Válassza az Erőforrás létrehozása lehetőséget.
- Statikus webalkalmazások keresése.
- Válassza a Static Web Apps elemet.
- 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.
Válassza Next.js a Build Presets legördülő listában.
Tartsa meg az alapértelmezett értéket az Alkalmazás helye mezőben.
Hagyja üresen az Api-hely mezőt.
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
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
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 .
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( ... ); }
Importálja
unstable_noStore
ésnext/cache
hívja meg azHome
ö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.
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.
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.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}.` }); }
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.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.
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> ); }
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:
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).*)', ], }
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, }, ] }, };
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:
- Nyissa meg az Azure Portalt.
- Keressen rá az első web-static-appomra a felső keresősávon.
- Válassza ki az alkalmazás nevét.
- Válassza a Törlés lehetőséget.
- 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).