Next.js Standalone für Azure App Service vorbereiten

Zwei Deployment-Verträge, ein Build

Dieses Repository erzeugt mit next build eine Next.js-Anwendung und aktiviert in next.config.ts den Modus output: "standalone". Next.js schreibt dadurch einen minimalen Server nach .next/standalone/server.js und nimmt nur die für den Serverbetrieb ermittelten Dateien und Abhängigkeiten auf.

Das Standalone-Verzeichnis ist ein lokales Prüfartefakt. Der geplante Azure-Pfad bleibt ein Source-Deployment: Azure Developer CLI übergibt den Quellstand an App Service, dort führt Oryx Installation und Build aus. Ein Azure-Deployment wurde zum Veröffentlichungszeitpunkt dieses Artikels noch nicht ausgeführt.

Statische Dateien ergänzen

Next.js kopiert public/ und .next/static nicht automatisch in das Standalone-Verzeichnis. Deshalb läuft nach jedem Build scripts/prepare-standalone.mjs. Das Skript prüft die benötigten Verzeichnisse, ersetzt alte Kopien und erzeugt diese Struktur:

.next/standalone/
  public/
  .next/static/
  server.js

Der lokale Produktionsstart verwendet danach:

npm run build
npm start

npm start startet in diesem Repository ausdrücklich .next/standalone/server.js. Der generierte Server berücksichtigt die von App Service gesetzte Variable PORT.

Azure-Konfiguration

Die deklarierte Zielruntime ist Node.js 24 LTS auf Azure App Service Linux. Der Bicep-Vertrag setzt NODE|24-lts, behält den B1-Plan bei und verwendet npm start als Startkommando. Für den Build aus der Quelle sind SCM_DO_BUILD_DURING_DEPLOYMENT und ENABLE_ORYX_BUILD aktiviert.

Zur Betriebsdiagnose beschreibt die Infrastruktur zusätzlich:

• einen Health Check auf /api/health,
• eine user-assigned Managed Identity,
• workspace-basiertes Application Insights,
• App-Service-Logs und Metriken über Diagnostic Settings.

Diese Ressourcenbeschreibung ist lokal kompiliert. Ob sie bestehende Azure-Ressourcen unverändert wiederverwendet, muss vor jeder Bereitstellung mit bestätigtem Subscription-Kontext, ARM-Validierung und What-if geprüft werden.

Reproduzierbare Prüfung

Der Befehl npm run verify führt Typprüfung, ESLint, Tests und Produktions-Build nacheinander aus. Damit werden Anwendungslogik und Standalone-Artefakt gemeinsam geprüft. Die Azure-Prüfung bleibt davon getrennt: Ein grüner lokaler Build ist notwendig, aber kein Nachweis für eine erfolgreiche Bereitstellung.

Diese Trennung hält drei Aussagen auseinander:

1. Der Quellcode ist typisiert und getestet.
2. Das lokale Standalone-Artefakt kann erzeugt werden.
3. Die Azure-Ressourcen und das Deployment sind erst nach eigener Validierung freigegeben.