Distribuera hybrid-Next.js-webbplatser i Azure Static Web Apps (förhandsversion)

Artikel
03/20/2024

I den här självstudien lär du dig att distribuera en Next.js webbplats till Azure Static Web Apps med hjälp av stöd för Next.js funktioner som React Server Components, Server-Side Rendering (SSR) och API-vägar.

Kommentar

Next.js hybridstöd finns i förhandsversion.

Förutsättningar

Ett Azure-konto med en aktiv prenumeration. Skapa ett konto utan kostnad.
Ett GitHub-konto. Skapa ett konto utan kostnad.
Node.js installerat.
Next.js CLI installerat. Mer information finns i guiden Next.js Komma igång.

Funktioner som inte stöds i förhandsversionen

Följande funktioner i Static Web Apps stöds inte för Next.js med hybridåtergivning:

Länkade API:er med Hjälp av Azure Functions, Azure App Service, Azure Container Apps eller Azure API Management.
Lokal emulering och distribution av SWA CLI.
Partiellt stöd för staticwebapp.config.json filen.
- Återställning efter navigering stöds inte.
- Dirigera omskrivningar till vägar i Next.js-programmet måste konfigureras i next.config.js.
- Konfigurationen i staticwebapp.config.json filen har företräde framför konfigurationen i next.config.js.
- Konfigurationen för den Next.js platsen ska hanteras med för next.config.js fullständig funktionskompatibilitet.
skip_app_build och skip_api_build kan inte användas i distributionsbilden Azure/static-web-apps-deploy@v1 .
Inkrementell statisk regenerering (ISR) stöder inte cachelagring av bilder.

Kommentar

Den maximala appstorleken för hybridprogrammet Next.js är 250 MB. Använd fristående funktion genom att Next.js för optimerade appstorlekar. Om detta inte räcker kan du överväga att använda statisk HTML-exporterad Next.js om kravet på appstorlek är mer än 250 MB.

Skapa en lagringsplats

Den här artikeln använder en GitHub-malllagringsplats för att göra det enkelt för dig att komma igång. Mallen har en startapp som ska distribueras till Azure Static Web Apps.

Gå till följande plats för att skapa en ny lagringsplats.

https://github.com/staticwebdev/nextjs-hybrid-starter/generate
Ge lagringsplatsen namnet my-first-static-web-app
Välj Create repository from template (Skapa lagringsplats från mall).

Skapa en statisk webbapp

Nu när lagringsplatsen har skapats kan du skapa en statisk webbapp från Azure-portalen.

Gå till Azure-portalen.
Välj Skapa en resurs.
Sök efter Static Web Apps.
Välj Static Web Apps.
Välj Skapa.

I avsnittet Grundläggande börjar du med att konfigurera din nya app och länka den till en GitHub-lagringsplats.

Skärmbild av avsnittet Grundläggande i Azure-portalen.

Inställning	Värde
Prenumeration	Välj din Azure-prenumerationen.
Resursgrupp	Välj länken Skapa ny och ange static-web-apps-test i textrutan.
Name	Ange my-first-static-web-app i textrutan.
Abonnemangstyp	Välj Kostnadsfri.
Information om Azure Functions och mellanlagring	Välj en region som är närmast dig.
Källa	Välj GitHub.

Välj Logga in med GitHub och autentisera med GitHub.

När du har loggat in med GitHub anger du lagringsplatsinformationen.

Inställning	Värde
Organisation	Välj din organisation.
Lagringsplats	Välj my-first-web-static-app.
Filial	Välj huvud.

Skärmbild av lagringsplatsinformation i Azure-portalen.

Kommentar

Om du inte ser några lagringsplatser:

Du kan behöva auktorisera Azure Static Web Apps i GitHub. Bläddra till din GitHub-lagringsplats och gå till Inställningar > Program > auktoriserade OAuth-appar, välj Azure Static Web Apps och välj sedan Bevilja.
Du kan behöva auktorisera Azure Static Web Apps i din Azure DevOps-organisation. Du måste vara ägare till organisationen för att bevilja behörigheterna. Begär programåtkomst från tredje part via OAuth. Mer information finns i Auktorisera åtkomst till REST-API:er med OAuth 2.0.

I avsnittet Bygginformation lägger du till konfigurationsinformation som är specifik för ditt önskade klientdelsramverk.

Välj Next.js i listrutan Skapa förinställningar .
Behåll standardvärdet i rutan Appplats .
Lämna rutan Api-plats tom.
Lämna rutan Appartefaktplats tom.

Välj Granska + skapa.

Skärmbild av knappen Skapa.

Visa webbplatsen

Det finns två aspekter för att distribuera en statisk app. Den första skapar de underliggande Azure-resurser som utgör din app. Det andra är ett arbetsflöde som skapar och publicerar ditt program.

Innan du kan gå till den nya statiska platsen måste distributionsversionen först slutföras.

Fönstret Översikt över statiska webbappar visar en serie länkar som hjälper dig att interagera med din webbapp.

Skärmbild av översiktsfönstret för Azure Static Web Apps.

Om du väljer på banderollen som säger väljer du här för att kontrollera statusen för dina GitHub Actions-körningar och tar dig till GitHub Actions som körs mot din lagringsplats. När du har kontrollerat att distributionsjobbet är klart kan du gå till din webbplats via den genererade URL:en.

När GitHub Actions-arbetsflödet är klart kan du välja URL-länken för att öppna webbplatsen på den nya fliken.

Konfigurera ditt Next.js projekt lokalt för att göra ändringar

Klona den nya lagringsplatsen till datorn. Ersätt <YOUR_GITHUB_ACCOUNT_NAME> med ditt kontonamn.
```
git clone http://github.com/<YOUR_GITHUB_ACCOUNT_NAME>/my-first-static-web-app
```
Öppna projektet i Visual Studio Code eller önskad kodredigerare.

Lägga till serverrederade data med en serverkomponent

Om du vill lägga till serveråtergivna data i ditt Next.js projekt med approuter redigerar du en Next.js komponent för att lägga till en serverdelsåtgärd för att återge data i komponenten. Som standard är Next.js komponenter serverkomponenter som kan återges server.

app/page.tsx Öppna filen och lägg till en åtgärd som anger värdet för en variabel, som beräknas på serversidan. Exempel är att hämta data eller andra serveråtgärder.
```
export default function Home() {
    const timeOnServer = new Date().toLocaleTimeString('en-US');
    return(
        ...
    );
}
```
Importera unstable_noStore från next/cache och anropa den i komponenten Home för att säkerställa att vägen återges dynamiskt.
```
import { unstable_noStore as noStore } from 'next/cache';

export default function Home() {
    noStore();

    const timeOnServer = new Date().toLocaleTimeString('en-US');
    return(
        ...
    );
}
```
Kommentar

I det här exemplet framtvingas dynamisk återgivning av den här komponenten för att demonstrera serverrendering av serverns aktuella tid. Approutermodellen för Next.js rekommenderar att du cachelagrar enskilda databegäranden för att optimera prestandan för din Next.js-app. Läs mer om datahämtning och cachelagring i Next.js.

Uppdatera komponenten Home i app/pages.tsx för att återge data på serversidan.

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

Lägga till en API-väg

Förutom serverkomponenter tillhandahåller Next.js routningshanterare som du kan använda för att skapa API-vägar till ditt Next.js program. Dessa API:er kan hämtas i Klientkomponenter.

Börja med att lägga till en API-väg.

Skapa en ny fil på app/api/currentTime/route.tsx. Den här filen innehåller routningshanteraren för den nya API-slutpunkten.

Lägg till en hanteringsfunktion för att returnera data från API:et.

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

Skapa en ny fil på app/components/CurrentTimeFromAPI.tsx. Den här komponenten skapar en container för klientkomponenten som hämtar API:et från webbläsaren.

Lägg till en klientkomponent som hämtar API:et i den här filen.

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

Den här klientkomponenten hämtar API:et med en useEffect React-krok för att återge komponenten när belastningen är klar. Direktivet 'use client' identifierar det här elementet som en klientkomponent. Mer information finns i Klientkomponenter.

Redigera app/page.tsx för att importera och återge CurrentTimeFromAPI klientkomponenten.

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

Resultatet från API-vägen visas på sidan.

Skärmbild som visar utdata från API-vägen.

Konfigurera körningsversionen för Next.js

Vissa Next.js versioner kräver specifika Node.js versioner. Om du vill konfigurera en specifik Node-version kan du ange egenskapen "motorer" för filen package.json för att ange en version.

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

Ange miljövariabler för Next.js

Next.js använder miljövariabler vid byggtiden och vid begäran för att stödja både statisk sidgenerering och dynamisk sidgenerering med återgivning på serversidan. Ange därför miljövariabler både i bygg- och distributionsuppgiften och i miljövariablerna för din Azure Static Web Apps-resurs.

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

Aktivera fristående funktion

När programstorleken överskrider 250 Mb hjälper funktionen Next.js utdatafilspårning till att optimera appens storlek och förbättra prestandan.

Utdatafilspårning skapar en komprimerad version av hela programmet med nödvändiga paketberoenden inbyggda i en mapp med namnet .next/standalone. Den här mappen är avsedd att distribueras på egen hand utan ytterligare node_modules beroenden.

För att aktivera standalone funktionen lägger du till följande ytterligare egenskap i :next.config.js

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

Du måste också konfigurera build kommandot i package.json filen för att kunna kopiera statiska filer till dina fristående utdata.

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

Konfigurera din Next.js routning och mellanprogram för distribution till Azure Static Web Apps

Ditt Next.js projekt kan konfigureras för anpassad hantering av vägar med omdirigeringar, omskrivningar och mellanprogram. Dessa hanterare används ofta för autentisering, anpassning, routning och internationalisering. Anpassad hantering påverkar standarddirigeringen för din Next.js plats och konfigurationen måste vara kompatibel med värd på Static Web Apps.

Static Web Apps verifierar att din Next.js webbplats har distribuerats genom att lägga till en sida på webbplatsen vid byggtillfället. Sidan heter public/.swa/health.html, och Static Web Apps verifierar att webbplatsen startas och distribueras genom att navigera till /.swa/health.html och verifiera ett lyckat svar. Mellanprogram och anpassad routning, som omfattar omdirigeringar och omskrivningar, kan påverka åtkomsten /.swa/health.html till sökvägen, vilket kan förhindra validering av static Web Apps-distribution. Följ dessa steg för att konfigurera mellanprogram och routning för en lyckad distribution till Static Web Apps:

Exkludera vägar som börjar med .swa i filen middleware.ts (eller .js) i mellanprogramskonfigurationen.

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

Konfigurera dina omdirigeringar i next.config.js för att exkludera vägar som börjar med .swa

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

Konfigurera omskrivningarna i next.config.js för att exkludera vägar som börjar med .swa

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

Dessa kodfragment utesluter sökvägar som börjar med .swa från att hanteras av din anpassade routning eller mellanprogram. Dessa regler säkerställer att sökvägarna matchar som förväntat under distributionsverifieringen.

Aktivera loggning för Next.js

Följ metodtipsen för felsökning av Next.js server-API:et och lägg till loggning i API:et för att fånga upp dessa fel. Loggning i Azure använder Application Insights. För att kunna förinläsa denna SDK måste du skapa ett anpassat startskript. Mer information:

Rensa resurser

Om du inte kommer att fortsätta att använda det här programmet kan du ta bort Azure Static Web Apps-instansen genom följande steg:

Öppna Azure Portal.
Sök efter my-first-web-static-app från det övre sökfältet.
Välj appnamnet.
Välj Ta bort.
Välj Ja för att bekräfta borttagningsåtgärden (den här åtgärden kan ta en stund att slutföra).

Nästa steg

Konfigurera appinställningar

Share via

Distribuera hybrid-Next.js-webbplatser i Azure Static Web Apps (förhandsversion)

Förutsättningar

Funktioner som inte stöds i förhandsversionen

Skapa en lagringsplats

Skapa en statisk webbapp

Visa webbplatsen

Konfigurera ditt Next.js projekt lokalt för att göra ändringar

Lägga till serverrederade data med en serverkomponent

Lägga till en API-väg

Konfigurera körningsversionen för Next.js

Ange miljövariabler för Next.js

Aktivera fristående funktion

Konfigurera din Next.js routning och mellanprogram för distribution till Azure Static Web Apps

Aktivera loggning för Next.js

Rensa resurser

Nästa steg

Ytterligare resurser