Bereitstellen von hybriden Next.js-Websites in Azure Static Web Apps (Vorschau)

  • Artikel

In diesem Tutorial lernen Sie, wie Sie eine Next.js-Website in Azure Static Web Apps bereitstellen und dabei die Unterstützung für Next.js-Funktionen wie React Server Components, Server-Side Rendering (SSR) und API-Routen nutzen.

Hinweis

Next.js Hybridunterstützung befindet sich in der Vorschau.

Voraussetzungen

Nicht unterstützte Funktionen in der Vorschauversion

Die folgenden Features statischer Web-Apps werden für Next.js mit Hybridrendering nicht unterstützt:

  • Verknüpfte APIs mit Azure Functions, Azure App Service, Azure Container Apps oder Azure API Management.
  • Lokale SWA CLI-Emulation und -Bereitstellung.
  • Nur teilweise Unterstützung für die staticwebapp.config.json-Datei.
    • Navigations-Fallback wird nicht unterstützt.
    • Das Umschreiben von Routen auf Routen innerhalb der Next.js-Anwendung muss in next.config.js konfiguriert werden.
    • Die Konfiguration in der Datei staticwebapp.config.json hat Vorrang vor der Konfiguration in next.config.js.
    • Die Konfiguration für die Next.js-Website sollte mit next.config.js erfolgen, um die volle Funktionskompatibilität zu gewährleisten.
  • skip_app_build und skip_api_build kann nicht innerhalb des Azure/static-web-apps-deploy@v1 Bereitstellungsimages verwendet werden.
  • ISR (Inkrementelle statische Regeneration) unterstützt nicht das Zwischenspeichern von Images.

Hinweis

Die maximale App-Größe für die hybride Next.js Anwendung beträgt 250 MB. Verwenden Sie eigenständige Features von Next.js für optimierte App-Größen. Wenn dies nicht ausreicht, sollten Sie erwägen, denstatischen HTML-Export von Next.js zu verwenden, wenn Ihre App mehr als 250 MB benötigt.

Erstellen eines Repositorys

In diesem Artikel wird ein GitHub-Vorlagenrepository verwendet, um Ihnen den Einstieg zu erleichtern. Die Vorlage enthält eine Starter-App zur Bereitstellung in Azure Static Web Apps.

  1. Navigieren Sie zum folgenden Speicherort, um ein neues Repository zu erstellen:

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

  2. Geben Sie Ihrem Repository den Namen my-first-static-web-app.

  3. Wählen Sie Create repository from template (Repository aus Vorlage erstellen) aus.

    Screenshot der Schaltfläche

Erstellen einer statischen Web-App

Nachdem das Repository nun erstellt wurde, können Sie im Azure-Portal eine statische Web-App erstellen.

  1. Öffnen Sie das Azure-Portal.
  2. Klicken Sie auf Ressource erstellen.
  3. Suchen Sie nach Static Web Apps.
  4. Klicken Sie auf statische Web-Apps.
  5. Klicken Sie auf Erstellen.

Konfigurieren Sie im Abschnitt Grundlagen zunächst Ihre neue App, und verknüpfen Sie sie mit einem GitHub-Repository.

Screenshot: Registerkarte „Grundlagen“ im Azure-Portal

Einstellung Wert
Subscription Wählen Sie Ihr Azure-Abonnement.
Ressourcengruppe Wählen Sie den Link Neu erstellen aus, und geben Sie in das Textfeld static-web-apps-test ein.
Name Geben Sie my-first-static-web-app in das Textfeld ein.
Plantyp Wählen Sie Free aus.
Details zu Azure Functions und Staging Wählen Sie die Region aus, die Ihnen am nächsten ist.
`Source` Wählen Sie GitHub aus.

Wählen Sie Mit GitHub anmelden aus, und authentifizieren Sie sich bei GitHub.

Geben Sie nach der Anmeldung mit GitHub die Informationen zum Repository ein.

Einstellung Wert
Organization Wählen Sie Ihre Organisation aus.
Repository Wählen Sie my-first-web-static-app aus.
Verzweigung Wählen Sie main aus.

Screenshot der Repositorydetails im Azure-Portal.

Hinweis

Wenn keine Repositorys angezeigt werden:

  • Sie müssen möglicherweise Azure Static Web Apps in GitHub autorisieren. Navigieren Sie zu Ihrem GitHub-Repository, wechseln Sie zu Einstellungen > Anwendungen > Autorisierte OAuth-Apps, und wählen Sie Azure Static Web Apps und dann Zuweisen aus.
  • Möglicherweise müssen Sie Azure Static Web Apps in Ihrer Azure DevOps-Organisation autorisieren. Sie müssen Besitzer der Organisation sein, um die Berechtigungen erteilen zu können. Fordern Sie über OAuth Zugriff auf Anwendungen von Drittanbietern an. Weitere Informationen finden Sie unter Autorisieren des Zugriffs auf REST-APIs mit OAuth 2.0.

Fügen Sie im Abschnitt Builddetails die für Ihr bevorzugtes Front-End-Framework spezifischen Konfigurationsdetails hinzu.

  1. Wählen Sie Next.js aus der Dropdownliste Buildvoreinstellungen aus.

  2. Behalten Sie den Standardwert im Feld App-Speicherort bei.

  3. Lassen Sie das Feld API-Speicherort leer.

  4. Lassen Sie das Feld Speicherort für App-Artefakte leer.

Klicken Sie auf Überprüfen + erstellen.

Screenshot der Schaltfläche

Anzeigen der Website

Für die Bereitstellung einer statischen App gelten zwei Aspekte. Im ersten werden die zugrunde liegenden Azure-Ressourcen erstellt, aus denen Ihre App besteht. Der zweite besteht aus einem Workflow, mit dem Ihre Anwendung erstellt und veröffentlicht wird.

Bevor Sie zu Ihrer neuen statischen Website navigieren können, muss zuvor der Buildvorgang für die Bereitstellung abgeschlossen sein.

Im Fenster Übersicht von Azure Static Web Apps werden einige Links angezeigt, die Ihnen als Hilfe bei der Interaktion mit Ihrer Web-App dienen.

Screenshot des Übersichtsfensters für Azure Static Web Apps.

Wenn Sie das Banner Hier klicken, um den Status Ihrer GitHub Actions-Ausführungen zu überprüfen auswählen, gelangen Sie zu den GitHub Actions-Instanzen, die für Ihr Repository ausgeführt werden. Nachdem Sie sich vergewissert haben, dass der Bereitstellungsauftrag abgeschlossen ist, können Sie über die generierte URL zu Ihrer Website wechseln.

Nachdem der GitHub Actions-Workflow abgeschlossen ist, können Sie den URL-Link auswählen, um die Website auf einer neuen Registerkarte zu öffnen.

Richten Sie Ihr Next.js Projekt lokal ein, um Änderungen vorzunehmen

  1. Klonen Sie das neue Repository auf Ihrem Computer. Ersetzen Sie „<YOUR_GITHUB_ACCOUNT_NAME>“ durch den Namen Ihres Kontos.

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

  2. Öffnen Sie das Projekt in Visual Studio Code oder ihrem bevorzugten Code-Editor.

Hinzufügen von vom Server gerenderten Daten mit einer Serverkomponente

Um serverrenderte Daten in Ihrem Next.js Projekt mithilfe des App-Routers hinzuzufügen, bearbeiten Sie eine Next.js Komponente, um serverseitige Vorgänge zum Rendern von Daten in der Komponente hinzuzufügen. Standardmäßig sind Next.js Komponenten Serverkomponenten , die vom Server gerendert werden können.

  1. Öffnen Sie die app/page.tsx Datei, und fügen Sie einen Vorgang hinzu, der den Wert einer Variablen festlegt, die serverseitig berechnet wird. Beispiele hierfür sind das Abrufen von Daten oder anderen Servervorgängen.

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

  2. Importieren sie unstable_noStore aus next/cache der Home Komponente, und rufen Sie sie auf, um sicherzustellen, dass die Route dynamisch gerendert wird.

    import { unstable_noStore as noStore } from 'next/cache';

export default function Home() {
    noStore();

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

    Hinweis

    In diesem Beispiel wird das dynamische Rendering dieser Komponente erzwungen, um das Serverrendering der aktuellen Zeit des Servers zu veranschaulichen. Das App Router-Modell von Next.js empfiehlt, einzelne Datenanforderungen zwischenzuspeichern, um die Leistung Ihrer Next.js App zu optimieren. Weitere Informationen zum Abrufen und Zwischenspeichern von Daten finden Sie in Next.js.

  3. Aktualisieren Sie die Home Komponente in "app/pages.tsx ", um die serverseitigen Daten zu rendern.

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

Hinzufügen einer API-Route

Zusätzlich zu Serverkomponenten stellt Next.js Routenhandler bereit, die Sie zum Erstellen von API-Routen zu Ihrer Next.js Anwendung verwenden können. Diese APIs können in Clientkomponentenabgerufen werden.

Beginnen Sie mit dem Hinzufügen einer API-Route.

  1. Erstellen Sie eine neue Datei vom Typ app/api/currentTime/route.tsx. Diese Datei enthält den Route-Handler für den neuen API-Endpunkt.

  2. Fügen Sie eine Handlerfunktion hinzu, um Daten über die API zurückzugeben.

    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. Erstellen Sie eine neue Datei vom Typ app/components/CurrentTimeFromAPI.tsx. Diese Komponente erstellt einen Container für die Clientkomponente, der die API aus dem Browser abruft.

  4. Fügen Sie eine Clientkomponente hinzu, die die API in dieser Datei abruft.

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

Diese Clientkomponente ruft die API mit einem useEffect React-Hook ab, um die Komponente nach Abschluss des Ladevorgangs zu rendern. Die 'use client' Direktive identifiziert dieses Element als Clientkomponente. Weitere Informationen finden Sie unter Clientbibliotheken.

  1. Bearbeiten Sie "app/page.tsx ", um die CurrentTimeFromAPI Clientkomponente zu importieren und zu rendern.

    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. Das Ergebnis der API-Route wird auf der Seite angezeigt.

Screenshot der Anzeige der Ausgabe aus der API-Route.

Konfigurieren der Laufzeitversion für Next.js

Bestimmte Next.js Versionen erfordern bestimmte Node.js Versionen. Um eine bestimmte Node-Version zu konfigurieren, können Sie die Eigenschaft "Engines" Ihrer package.json Datei festlegen, um eine Version festzulegen.

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

Festlegen von Umgebungsvariablen für Next.js

Next.js verwendet Umgebungsvariablen zur Erstellungszeit und zur Anforderungszeit, um sowohl die statische Seitengenerierung als auch die dynamische Seitengenerierung mit serverseitigem Rendering zu unterstützen. Legen Sie daher Umgebungsvariablen sowohl innerhalb des Buildvorgangs als auch in den Umgebungsvariablen Ihrer Azure Static Web Apps-Ressource fest.

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

Aktivieren eigenständiger Features

Wenn die Anwendungsgröße 250 MB überschreitet, hilft das Next.js-Feature Ausgabedateiablaufverfolgung, die App-Größe zu optimieren und die Leistung zu verbessern.

Die Ablaufverfolgung von Ausgabedateien erstellt eine komprimierte Version der gesamten Anwendung mit den erforderlichen Paketabhängigkeiten, die in einen Ordner mit der Bezeichnung .next/standalone integriert sind. Dieser Ordner soll eigenständig und ohne zusätzliche node_modules-Abhängigkeiten bereitgestellt werden.

Um das Feature standalone zu aktivieren, fügen Sie Ihrer next.config.jsdie folgende zusätzliche Eigenschaft hinzu:

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

Sie müssen auch den build Befehl in der package.json Datei konfigurieren, um statische Dateien in Ihre eigenständige Ausgabe zu kopieren.

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

Konfigurieren Ihres Next.js Routings und Middleware für die Bereitstellung in Azure Static Web Apps

Ihr Next.js Projekt kann so konfiguriert werden, dass es eine benutzerdefinierte Verarbeitung von Routen mit Umleitungen, Umschreibungen und Middleware ermöglicht. Diese Handler werden häufig für Authentifizierung, Personalisierung, Routing und Internationalisierung verwendet. Die benutzerdefinierte Behandlung wirkt sich auf das Standardrouting Ihrer Next.js-Website aus, und die Konfiguration muss mit dem Hosting in Static Web Apps kompatibel sein.

Statische Web-Apps überprüfen, ob Ihre Next.js Website erfolgreich bereitgestellt wird, indem Sie ihrer Website zur Erstellungszeit eine Seite hinzufügen. Die Seite ist benannt public/.swa/health.html, und Static Web Apps überprüft den erfolgreichen Start und die Bereitstellung Ihrer Website, indem sie zu /.swa/health.html einer erfolgreichen Antwort navigieren und überprüfen. Middleware und benutzerdefiniertes Routing, das Umleitungen und Umschreibungen umfasst, können sich auf den Zugriff des /.swa/health.html Pfads auswirken, wodurch die Bereitstellungsüberprüfung von Statischen Web Apps verhindert werden kann. Führen Sie die folgenden Schritte aus, um Middleware und Routing für eine erfolgreiche Bereitstellung in Static Web Apps zu konfigurieren:

  1. Schließen Sie Routen aus, die mit .swa Ihrer middleware.ts (oder .js ) Datei in Ihrer Middleware-Konfiguration beginnen.

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

  2. Konfigurieren Sie Ihre Umleitungen next.config.js so, dass routen beginnend mit .swa

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

  3. Konfigurieren Sie Ihre Neuschreibungen next.config.js so, dass routen beginnend mit .swa

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

Diese Codeausschnitte schließen Pfade aus, die mit .swa der Verarbeitung durch Ihr benutzerdefiniertes Routing oder Middleware beginnen. Diese Regeln stellen sicher, dass die Pfade während der Bereitstellungsüberprüfung wie erwartet aufgelöst werden.

Aktivieren der Protokollierung für Next.js

Fügen Sie der API nach bewährten Methoden für die Problembehandlung bei der Next.js-Server-API die Protokollierung hinzu, um diese Fehler abzufangen. Die Protokollierung in Azure verwendet Application Insights. Um dieses SDK vorab zu laden, müssen Sie ein benutzerdefiniertes Startskript erstellen. Weitere Informationen:

Bereinigen von Ressourcen

Falls Sie diese Anwendung nicht weiter nutzen möchten, können Sie die Azure Static Web Apps-Instanz mit den folgenden Schritten löschen:

  1. Öffnen Sie das Azure-Portal.
  2. Suchen Sie über die obere Suchleiste nach my-first-web-static-app.
  3. Wählen Sie den App-Namen aus.
  4. Klicken Sie auf Löschen.
  5. Klicken Sie auf Ja, um die Löschaktion zu bestätigen (diese Aktion kann einige Minuten dauern).

Nächste Schritte

Konfigurieren von App-Einstellungen