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

Artikel
07/01/2024

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

Resource	BESCHREIBUNG
Azure-Konto	Falls Sie kein Azure-Konto mit einem aktiven Abonnement haben, können Sie eines kostenlos erstellen.
GitHub-Konto	Falls Sie kein GitHub-Konto besitzen, können Sie kostenlos ein Konto erstellen.
Node.js	Installieren Sie die neueste Version von Node.js.
Next.js CLI	Installieren Sie die neueste Version der Next.js-CLI. Einzelheiten finden Sie im Leitfaden Next.js: Erste Schritte.

Nicht unterstützte Funktionen in der Vorschauversion

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

Bestimmte Azure-Dienste: Verknüpfte APIs, die Azure Functions, Azure App Service, Azure Container Apps oder Azure API Management nutzen
SWA CLI-Features: Lokale SWA CLI-Emulation und -Bereitstellung
Partielle Featureunterstützung: Die folgenden Eigenschaften in der Datei staticwebapp.config.json werden nicht unterstützt:
- 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.
Buildüberspringen: Bei Next.js-Anwendungen entfernt Static Web Apps bei skip_api_build=true keine Entwicklungsabhängigkeiten und fügt standardmäßig das sharp-Paket nicht hinzu. Wenn Sie diese Optimierungen benötigen, fügen Sie sie Ihren benutzerdefinierten Buildschritten hinzu, bevor Sie skip_app_build=true übergeben.
Inkrementelle statische Regeneration (ISR): Das Zwischenspeichern von Images wird nicht unterstützt.

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.

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

https://github.com/staticwebdev/nextjs-hybrid-starter/generate
Geben Sie Ihrem Repository den Namen my-first-static-web-app.
Wählen Sie Create repository from template (Repository aus Vorlage erstellen) aus.

Erstellen einer statischen Web-App

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

Öffnen Sie das Azure-Portal.
Klicken Sie auf Ressource erstellen.
Suchen Sie nach Static Web Apps.
Klicken Sie auf statische Web-Apps.
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.
Quelle	Wählen Sie GitHub aus, und melden Sie sich ggf. bei GitHub an.

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.

Wählen Sie Next.js aus der Dropdownliste Buildvoreinstellungen aus.
Behalten Sie den Standardwert im Feld App-Speicherort bei.
Lassen Sie das Feld API-Speicherort leer.
Lassen Sie das Feld Ausgabespeicherort 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

Klonen Sie das neue Repository auf Ihrem Computer. Ersetzen Sie <GITHUB_ACCOUNT_NAME> durch den Namen Ihres Kontos.
```
git clone http://github.com/<GITHUB_ACCOUNT_NAME>/my-first-static-web-app
```
Öffnen Sie das Projekt in Visual Studio Code oder ihrem bevorzugten Code-Editor.

Einrichten des serverseitigen Renderings

Für jede hybride Next.js-Bereitstellung in allen Plänen ist automatisch ein verwaltetes Back-End verfügbar. Sie können die Leistung jedoch optimieren und mehr Kontrolle über das Back-End übernehmen, indem Sie Ihrer Website ein benutzerdefiniertes Back-End zuweisen. Wenn Sie zwischen einem verwalteten Back-End und einem verknüpften Back-End wechseln, kommt es zu keiner Downtime bei Ihrer Website.

Eigenes Back-End verwenden (Bring your own backend)

Sie können die Leistung verbessern und mehr Kontrolle über das serverseitige Rendering von Next.js erhalten, wenn Sie Ihr Back-End verwenden. Führen Sie die folgenden Schritte aus, um ein benutzerdefiniertes Back-End für Ihre Website einzurichten.

In den folgenden Schritten wird gezeigt, wie Sie Static Web Apps mit dem Plan „Standard“ oder höher mit einem benutzerdefinierten Back-End verknüpfen.

Hinweis

Verknüpfte Back-Ends sind nur für Websites verfügbar, bei denen der Plan „Standard“ oder höher verwendet wird.

Wechseln Sie im Azure-Portal zu Ihrer statischen Web-App.
Wählen Sie im seitlichen Menü die Option Einstellungen und dann APIs aus.
Wählen Sie Configure linked backend (Verknüpftes Back-End konfigurieren) aus.
Erstellen Sie einen neuen App Service-Plan, oder wählen Sie einen vorhandenen App Service-Plan aus.

Ihr ausgewählter App Service-Plan muss mindestens eine S1-SKU verwenden.
Klicke auf Link (Verknüpfen).

Hinzufügen von vom Server gerenderten Daten mit einer Serverkomponente

Um serverseitig gerenderte Daten in Ihrem Next.js-Projekt mit dem App-Router hinzuzufügen, bearbeiten Sie eine Next.js-Komponente, um einen serverseitigen Vorgang zum Rendern von Daten in der Komponente hinzuzufügen. Standardmäßig sind Next.js Komponenten Serverkomponenten , die vom Server gerendert werden können.

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

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. Sie können diese APIs in Clientkomponenten abrufen.

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

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.

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

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.

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.

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

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 engines-Eigenschaft Ihrer package.json-Datei festlegen, um eine Version anzugeben.

{
  ...
  "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. Dieses Paket ist in einen Ordner namens .next/standalone integriert. Mit diesem Paket kann Ihre App eigenständig ohne node_modules-Abhängigkeiten bereitgestellt werden.

Um das Feature standalone zu aktivieren, fügen Sie Ihrer next.config.js-Datei die folgende Eigenschaft hinzu:

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

Konfigurieren Sie als Nächstes den Befehl build in der package.json-Datei, 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 von Routing und Middleware für die Bereitstellung

Sie können die Routenverarbeitung Ihres Next.js-Projekts mit benutzerdefinierten Umleitungen, Umschreibungen und Middleware konfigurieren. 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:

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).*)',
  ],
}

Konfigurieren Sie Ihre Umleitungen in next.config.js so, dass Routen ausgeschlossen werden, die mit .swa beginnen.

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

Konfigurieren Sie Ihre Umschreibungsregeln in next.config.js so, dass Routen ausgeschlossen werden, die mit .swa beginnen.

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

Diese Codeausschnitte schließen Pfade aus, die mit .swa beginnen. So wird verhindert, dass Ihre benutzerdefinierten Routing- oder Middleware-Konfigurationen diese Anforderungen verarbeiten. 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:

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

Nächste Schritte

Konfigurieren von App-Einstellungen

Freigeben über

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

Voraussetzungen

Nicht unterstützte Funktionen in der Vorschauversion

Erstellen eines Repositorys

Erstellen einer statischen Web-App

Anzeigen der Website

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

Einrichten des serverseitigen Renderings

Eigenes Back-End verwenden (Bring your own backend)

Hinzufügen von vom Server gerenderten Daten mit einer Serverkomponente

Hinzufügen einer API-Route

Konfigurieren der Laufzeitversion für Next.js

Festlegen von Umgebungsvariablen für Next.js

Aktivieren eigenständiger Features

Konfigurieren von Routing und Middleware für die Bereitstellung

Aktivieren der Protokollierung für Next.js

Bereinigen von Ressourcen

Nächste Schritte

Feedback

Zusätzliche Ressourcen