Nasazení hybridních Next.js webů ve službě Azure Static Web Apps (Preview)

Článek
06/13/2024

V tomto kurzu se naučíte nasadit web Next.js do Azure Static Web Apps s využitím podpory pro funkce Next.js, jako jsou react serverové komponenty, vykreslování na straně serveru (SSR) a trasy rozhraní API.

Poznámka:

Next.js hybridní podpora je ve verzi Preview.

Požadavky

Resource	Popis
Účet Azure	Pokud nemáte účet Azure s aktivním předplatným, můžete si ho zdarma vytvořit.
Účet GitHub	Pokud účet GitHub nemáte, můžete si ho zdarma vytvořit.
Node.js	Nainstalujte nejnovější verzi Node.js.
rozhraní příkazového řádku Next.js	Nainstalujte nejnovější verzi rozhraní příkazového řádku Next.js. Podrobnosti najdete v průvodci začínáme Next.js.

Nepodporované funkce ve verzi Preview

Pro Next.js s hybridním vykreslováním se nepodporují následující funkce Static Web Apps:

Výběr služeb Azure: Propojená rozhraní API pomocí Azure Functions, Aplikace Azure Service, Azure Container Apps nebo Azure API Management.
Funkce rozhraní příkazového řádku SWA: Místní emulace a nasazení rozhraní příkazového řádku SWA
Podpora částečných funkcí: Následující vlastnosti v staticwebapp.config.json souboru nejsou podporované:
- Záložní navigace není podporována.
- Směrování přepisuje trasy v rámci Next.js aplikace musí být nakonfigurované v rámci next.config.js.
- Konfigurace v souboru staticwebapp.config.json má přednost před konfigurací v rámci next.config.jssouboru .
- Konfigurace pro Next.js lokalitu by měla být zpracována pomocí next.config.js úplné kompatibility funkcí.
Přeskočení sestavení: Pro Next.js aplikace, pokud skip_api_build=truestatické webové aplikace neodeberou vývojové závislosti nebo ve výchozím nastavení nepřidají ostrý balíček. Pokud chcete tyto optimalizace, před předáním skip_app_build=trueje přidejte do vlastních kroků sestavení .
Přírůstková statická regenerace (ISR): Ukládání obrázků do mezipaměti se nepodporuje.

Poznámka:

Maximální velikost aplikace pro hybridní Next.js aplikace je 250 MB. Pro optimalizované velikosti aplikací používejte samostatnou funkci Next.js. Pokud to nestačí, zvažte použití statického HTML exportovaného Next.js , pokud je váš požadavek na velikost aplikace větší než 250 MB.

Vytvoření úložiště

Tento článek používá úložiště šablon GitHubu, abyste mohli snadno začít. Šablona obsahuje úvodní aplikaci pro nasazení do Azure Static Web Apps.

Přejděte do následujícího umístění a vytvořte nové úložiště.

https://github.com/staticwebdev/nextjs-hybrid-starter/generate
Pojmenujte své úložiště my-first-static-web-app
Vyberte možnost Create repository from template (Vytvořit úložiště ze šablony).

Vytvoření statické webové aplikace

Teď, když je úložiště vytvořené, můžete vytvořit statickou webovou aplikaci z webu Azure Portal.

Přejděte na Azure Portal.
Vyberte Vytvořit prostředek.
Vyhledejte statické webové aplikace.
Vyberte staické webové aplikace (Static Web Apps).
Vyberte Vytvořit.

V části Základy začněte tím, že nakonfigurujete novou aplikaci a propojíte ji s úložištěm GitHub.

Snímek obrazovky s částí Základy na webu Azure Portal

Nastavení	Hodnota
Předplatné	Vyberte své předplatné Azure.
Skupina prostředků	Vyberte odkaz Vytvořit nový a do textového pole zadejte static-web-apps-test.
Název	Do textového pole zadejte my-first-static-web-app .
Typ plánu	Vyberte Free.
Zdroj	V případě potřeby vyberte GitHub a přihlaste se k GitHubu.

Vyberte Přihlášení pomocí GitHubu a ověřte se pomocí GitHubu.

Po přihlášení pomocí GitHubu zadejte informace o úložišti.

Nastavení	Hodnota
Organizace	Vyberte svoji organizaci.
Repository	Vyberte my-first-web-static-app.
Pobočka	Vyberte hlavní.

Snímek obrazovky s podrobnostmi úložiště na webu Azure Portal

Poznámka:

Pokud nevidíte žádná úložiště:

Možná budete muset autorizovat Azure Static Web Apps na GitHubu. Přejděte do úložiště GitHub a přejděte do části Aplikace Nastavení > Autorizované aplikace > OAuth, vyberte Azure Static Web Apps a pak vyberte Udělit.
Možná budete muset autorizovat Azure Static Web Apps ve vaší organizaci Azure DevOps. Abyste mohli udělit oprávnění, musíte být vlastníkem organizace. Požádejte o přístup k aplikacím třetích stran prostřednictvím OAuth. Další informace najdete v tématu Autorizace přístupu k rozhraním REST API pomocí OAuth 2.0.

V části Podrobnosti sestavení přidejte podrobnosti konfigurace specifické pro preferovanou front-endovou architekturu.

V rozevíracím seznamu Předvolby sestavení vyberte Next.js.
Ponechte výchozí hodnotu v poli Umístění aplikace.
Pole Umístění rozhraní API nechte prázdné.
Pole Umístění výstupu nechte prázdné.

Vyberte Zkontrolovat a vytvořit.

Snímek obrazovky s tlačítkem Vytvořit

Zobrazení webu

Nasazení statické aplikace má dva aspekty. První vytvoří podkladové prostředky Azure, které tvoří vaši aplikaci. Druhým je pracovní postup, který sestaví a publikuje vaši aplikaci.

Než budete moct přejít na novou statickou lokalitu, musí se sestavení nasazení nejprve dokončit.

V okně Přehled statických webových aplikací se zobrazí řada odkazů, které vám pomůžou pracovat s webovou aplikací.

Snímek obrazovky s oknem přehledu Azure Static Web Apps

Výběrem na banneru, který říká, že výběrem sem zkontrolujete stav spuštění GitHub Actions, přejdete na GitHub Actions spuštěné v úložišti. Jakmile ověříte, že je úloha nasazení dokončená, můžete přejít na web přes vygenerovanou adresu URL.

Po dokončení pracovního postupu GitHub Actions můžete vybrat odkaz na adresu URL a otevřít web na nové kartě.

Místní nastavení projektu Next.js pro provádění změn

Naklonujte nové úložiště do počítače. Nezapomeňte nahradit <GITHUB_ACCOUNT_NAME> názvem vašeho účtu.
```
git clone http://github.com/<GITHUB_ACCOUNT_NAME>/my-first-static-web-app
```
Otevřete projekt v editoru Visual Studio Code nebo v preferovaném editoru kódu.

Nastavení vykreslování na straně serveru

Spravovaná zálohovaná služba je automaticky dostupná pro každé hybridní Next.js nasazení ve všech plánech. Výkon ale můžete vyladit a převzít větší kontrolu nad back-endem tím, že k webu přiřadíte vlastní back-end. Pokud přepnete mezi spravovaným back-endem na propojený back-end, váš web nebude mít žádný výpadek.

Používání vlastního back-endu

Při přenesení back-endu můžete zvýšit výkon a získat větší kontrolu nad vykreslováním na straně Next.js serveru. Pomocí následujících kroků nastavte vlastní back-end pro váš web.

Následující kroky ukazují, jak přidružit vlastní back-end k plánu Standard a nad statickými webovými aplikacemi.

Poznámka:

Propojené back-endy jsou dostupné jenom pro weby používající plán Standard nebo vyšší.

Na webu Azure Portal přejděte do své statické webové aplikace.
V boční nabídce vyberte Nastavení a pak rozhraní API.
Vyberte Konfigurovat propojený back-end.
Vytvořte nový plán služby App Service nebo vyberte existující plán služby App Service.

Vybraný plán služby App Service musí používat aspoň skladovou položku S1 .
Klikněte na Odkaz.

Přidání dat vykreslených serverem pomocí součásti serveru

Pokud chcete přidat data vykreslená serverem do projektu Next.js pomocí směrovače aplikací, upravte komponentu Next.js a přidejte operaci na straně serveru pro vykreslení dat v komponentě. Ve výchozím nastavení jsou součásti Next.js serverové součásti , které lze vykreslit.

app/page.tsx Otevřete soubor a přidejte operaci, která nastaví hodnotu vypočítané proměnné na straně serveru. Mezi příklady patří načítání dat nebo jiných operací serveru.
```
export default function Home() {
    const timeOnServer = new Date().toLocaleTimeString('en-US');
    return(
        ...
    );
}
```
Importujte unstable_noStore z next/cache komponenty a volejte ji v rámci Home komponenty, abyste zajistili dynamické vykreslení trasy.
```
import { unstable_noStore as noStore } from 'next/cache';

export default function Home() {
    noStore();

    const timeOnServer = new Date().toLocaleTimeString('en-US');
    return(
        ...
    );
}
```
Poznámka:

Tento příklad vynutí dynamické vykreslování této komponenty k předvedení vykreslování serveru aktuálního času serveru. Model směrovače aplikací Next.js doporučuje ukládání jednotlivých požadavků na data do mezipaměti, aby se optimalizoval výkon Next.js aplikace. Přečtěte si další informace o načítání dat a ukládání do mezipaměti v Next.js.

Aktualizujte komponentu Home v souboru app/pages.tsx , aby se vykreslila data na straně serveru.

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

Přidání trasy rozhraní API

Kromě komponent serveru poskytuje Next.js obslužné rutiny tras, které můžete použít k vytváření tras rozhraní API do Next.js aplikace. Tato rozhraní API můžete načíst v klientských komponentách.

Začněte přidáním trasy rozhraní API.

Vytvořte nový soubor na adrese app/api/currentTime/route.tsx. Tento soubor obsahuje obslužnou rutinu trasy pro nový koncový bod rozhraní API.

Přidejte funkci obslužné rutiny pro vrácení dat z rozhraní API.

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

Vytvořte nový soubor na adrese app/components/CurrentTimeFromAPI.tsx. Tato komponenta vytvoří kontejner pro klientskou komponentu, která načte rozhraní API z prohlížeče.

Přidejte klientskou komponentu, která načte rozhraní API v tomto souboru.

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

Tato klientská komponenta načte rozhraní API pomocí useEffect háku React pro vykreslení komponenty po dokončení načtení. Direktiva 'use client' identifikuje tento prvek jako součást klienta. Další informace naleznete v tématu Klientské komponenty.

Upravte soubor app/page.tsx pro import a vykreslení CurrentTimeFromAPI klientské komponenty.

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

Výsledek trasy rozhraní API se zobrazí na stránce.

Snímek obrazovky znázorňující výstup z trasy rozhraní API

Konfigurace verze modulu runtime pro Next.js

Některé verze Next.js vyžadují konkrétní verze Node.js. Pokud chcete nakonfigurovat konkrétní verzi uzlu, můžete nastavit engines vlastnost package.json souboru tak, aby určila verzi.

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

Nastavení proměnných prostředí pro Next.js

Next.js používá proměnné prostředí v době sestavení a v době požadavku, aby podporovaly generování statických stránek i dynamické generování stránek pomocí vykreslování na straně serveru. Proto nastavte proměnné prostředí jak v rámci úlohy sestavení, tak nasazení a v proměnných prostředí vašeho prostředku Azure Static Web Apps.

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

Povolení samostatné funkce

Když velikost aplikace překročí 250 MB, funkce pro trasování výstupních souborů Next.js pomáhá optimalizovat velikost aplikace a zvýšit výkon.

Trasování výstupních souborů vytvoří komprimovanou verzi celé aplikace s nezbytnými závislostmi balíčku. Tento balíček je integrovaný do složky s názvem .next/standalone. S tímto balíčkem se aplikace může nasadit samostatně bez node_modules závislostí.

Chcete-li tuto funkci povolit standalone , přidejte do své next.config.jsslužby následující vlastnost:

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

Dále nakonfigurujte build příkaz v package.json souboru, aby se statické soubory zkopírovaly do samostatného výstupu.

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

Konfigurace směrování a middlewaru pro nasazení

Ke konfiguraci Next.js zpracování tras můžete použít vlastní přesměrování, přepsání a middleware. Tyto obslužné rutiny se běžně používají pro ověřování, přizpůsobení, směrování a internacionalizaci. Vlastní zpracování ovlivňuje výchozí směrování webu Next.js a konfigurace musí být kompatibilní s hostováním ve Static Web Apps.

Static Web Apps ověří, jestli je web Next.js úspěšně nasazený, a to přidáním stránky na web v době sestavení. Stránka má název public/.swa/health.htmla Static Web Apps ověří úspěšné spuštění a nasazení webu tak, že přejde na /.swa/health.html úspěšnou odpověď a ověří ji. Middleware a vlastní směrování, které zahrnuje přesměrování a přepsání, může ovlivnit přístup /.swa/health.html k cestě, což může zabránit ověření nasazení static Web Apps. Pokud chcete nakonfigurovat middleware a směrování pro úspěšné nasazení do Static Web Apps, postupujte takto:

Vylučte trasy začínající .swa v souboru middleware.ts (nebo .js) v konfiguraci middlewaru.

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

Nakonfigurujte přesměrování next.config.js tak, aby vyloučila trasy začínající na .swa.

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

Nakonfigurujte pravidla next.config.js přepsání tak, aby vyloučila trasy začínající na .swa.

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

Tyto fragmenty kódu vylučují cesty, které začínají .swa tím, že vaše vlastní směrování nebo middleware přestanou zpracovávat tyto požadavky. Tato pravidla zajišťují, aby se cesty během ověřování nasazení přeložily podle očekávání.

Povolení protokolování pro Next.js

Při řešení potíží s rozhraním API serveru Next.js postupujte podle osvědčených postupů a přidejte do rozhraní API protokolování, abyste tyto chyby zachytili. Protokolování v Azure používá Application Insights. Abyste mohli tuto sadu SDK předem načíst, musíte vytvořit vlastní spouštěcí skript. Další informace najdete v tématech:

Vyčištění prostředků

Pokud tuto aplikaci nebudete dál používat, můžete instanci Azure Static Web Apps odstranit pomocí následujících kroků:

Otevřete Azure Portal.
Na horním panelu hledání vyhledejte moji první webovou statickou aplikaci .
Vyberte název aplikace.
Vyberte Odstranit.
Výběrem možnosti Ano potvrďte akci odstranění (dokončení této akce může chvíli trvat).

Další kroky

Konfigurace nastavení aplikace

Sdílet prostřednictvím

Nasazení hybridních Next.js webů ve službě Azure Static Web Apps (Preview)

Požadavky

Nepodporované funkce ve verzi Preview

Vytvoření úložiště

Vytvoření statické webové aplikace

Zobrazení webu

Místní nastavení projektu Next.js pro provádění změn

Nastavení vykreslování na straně serveru

Používání vlastního back-endu

Přidání dat vykreslených serverem pomocí součásti serveru

Přidání trasy rozhraní API

Konfigurace verze modulu runtime pro Next.js

Nastavení proměnných prostředí pro Next.js

Povolení samostatné funkce

Konfigurace směrování a middlewaru pro nasazení

Povolení protokolování pro Next.js

Vyčištění prostředků

Další kroky

Váš názor

Další materiály