Build-Konfiguration für Azure Static Web Apps

  • Artikel

Die Azure Static Web Apps-Buildkonfiguration verwendet entweder GitHub Actions oder Azure Pipelines. Jede Site hat eine YAML-Konfigurationsdatei, die steuert, wie eine Site erstellt und bereitgestellt wird. In diesem Artikel werden Struktur und Optionen der Datei erläutert.

In der folgenden Tabelle sind die verfügbaren Konfigurationseinstellungen aufgeführt.

Eigenschaft Beschreibung Erforderlich
app_location In diesem Ordner befindet sich der Quellcode für Ihre Front-End-Anwendung. Der Wert ist relativ zum Stamm des Repositorys in GitHub und dem aktuellen Arbeitsordner in Azure DevOps. Bei Verwendung mit skip_app_build: true handelt es sich bei diesem Wert um den Buildausgabespeicherort der App. Ja
api_location Dieser Ordner enthält den Quellcode für Ihre API-Anwendung. Der Wert ist relativ zum Stamm des Repositorys in GitHub und dem aktuellen Arbeitsordner in Azure DevOps. Bei Verwendung mit skip_api_build: true handelt es sich bei diesem Wert um den Buildausgabespeicherort der API. No
output_location Wenn Ihre Webanwendung einen Build-Schritt ausführt, ist der Ausgabeort der Ordner, in dem die öffentlichen Dateien generiert werden. Bei den meisten Projekten ist der output_location relativ zum app_location. Bei .NET-Projekten ist der Speicherort jedoch relativ zum Ausgabeordner. No
app_build_command Für Node.js-Anwendungen können Sie einen benutzerdefinierten Befehl definieren, um die Anwendung mit statischen Inhalten zu erstellen.

Wenn Sie beispielsweise einen Produktionsbuild für eine Angular-Anwendung konfigurieren möchten, erstellen Sie ein npm-Skript mit dem Namen build-prod, um ng build --prod auszuführen, und geben Sie npm run build-prod als benutzerdefinierten Befehl ein. Wenn Sie das Feld leer lassen, versucht der Workflow, den Befehl npm run build oder npm run build:azure auszuführen.		 No
api_build_command Für Node.js-Anwendungen können Sie einen benutzerdefinierten Befehl definieren, um die Azure Functions API-Anwendung zu erstellen. No
skip_app_build Legen Sie den Wert auf true fest, um das Erstellen der Front-End-App zu überspringen. No
skip_api_build Legen Sie den Wert auf true fest, um das Erstellen der API-Funktionen zu überspringen. No
cwd
(Nur Azure Pipelines)		 Absoluter Pfad zum Arbeitsordner. Wird standardmäßig auf $(System.DefaultWorkingDirectory) festgelegt. No
build_timeout_in_minutes Legen Sie diesen Wert fest, um das Buildtimeout anzupassen. Wird standardmäßig auf 15 festgelegt. No

Mit diesen Einstellungen können Sie GitHub Actions oder Azure Pipelines einrichten, um kontinuierliche Integration/kontinuierliche Bereitstellung (CI/CD) für Ihre statische Webanwendung durchzuführen.

Name und Speicherort der Datei

Die GitHub Actions-Aktion generiert die Konfigurationsdatei und wird im Ordner .github/workflows gespeichert, der nach folgendem Format benannt ist: azure-static-web-apps-<RANDOM_NAME>.yml.

Standardmäßig wird die Konfigurationsdatei im Stammverzeichnis Ihres Repositorys unter dem Namen azure-pipelines.yml gespeichert.

Sicherheit

Sie können zwischen zwei verschiedenen Bereitstellungsautorisierungsrichtlinien wählen, um Ihre Buildkonfiguration zu schützen. Static Web Apps unterstützt entweder die Verwendung eines Azure-Bereitstellungstokens (empfohlen) oder eines GitHub-Zugriffstokens.

Führen Sie die folgenden Schritte aus, um die Bereitstellungsautorisierungsrichtlinie in Ihrer App festzulegen:

  • Neue Apps: Wenn Sie Ihre statische Web-App erstellen, treffen Sie auf der Registerkarte Bereitstellungskonfiguration eine Auswahl für die Bereitstellungsautorisierungsrichtlinie.

  • Vorhandene Apps: Um eine vorhandene App zu aktualisieren, navigieren Sie zu Einstellungen>Konfiguration>Bereitstellungskonfiguration, und treffen Sie eine Auswahl für die Bereitstellungsautorisierungsrichtlinie.

Buildkonfiguration

In der folgenden Beispielkonfiguration wird das Repository auf Änderungen überwacht. Wenn Commits in den main-Zweig gepusht werden, wird die Anwendung im app_location-Ordner erstellt und die Dateien im output_location-Ordner werden im öffentlichen Web bereitgestellt. Außerdem ist die Anwendung im Ordner api unter dem Pfad api der Website verfügbar.

trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    submodules: true
  - task: AzureStaticWebApp@0
    inputs:
      app_location: 'src' # App source code path relative to cwd
      api_location: 'api' # Api source code path relative to cwd
      output_location: 'public' # Built app content directory relative to app_location - optional
      cwd: '$(System.DefaultWorkingDirectory)/myapp' # Working directory - optional
      azure_static_web_apps_api_token: $(deployment_token)

In dieser Konfiguration:

  • Der main Zweig wird auf Commits überwacht.
  • Der app_location verweist auf den Ordner src, der die Quelldateien für die Webanwendung enthält. Dieser Wert ist relativ zum Arbeitsverzeichnis (cwd). Verwenden Sie /, um ihn auf das Arbeitsverzeichnis festzulegen.
  • Der api_location verweist auf den Ordner api, der die Azure Functions-Anwendung für die API-Endpunkte der Website enthält. Dieser Wert ist relativ zum Arbeitsverzeichnis (cwd). Verwenden Sie /, um ihn auf das Arbeitsverzeichnis festzulegen.
  • Der output_location verweist auf den Ordner public, der die endgültige Version der Quelldateien der App enthält. Dieser Wert ist relativ zu app_location. Bei .NET-Projekten ist der Speicherort relativ zum Ausgabeordner.
  • cwd ist ein absoluter Pfad, der auf das Arbeitsverzeichnis verweist. Es ist standardmäßig $(System.DefaultWorkingDirectory).
  • Die Variable $(deployment_token) verweist auf das generierte Azure DevOps Bereitstellungs-Token

Hinweis

app_location and api_location müssen relativ zum Arbeitsverzeichnis (cwd) sein, und sie müssen Unterverzeichnisse unter cwd sein.

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
      - dev
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    if: github.event_name == 'push' || (github.event_name == 'pull_request' && github.event.action != 'closed')
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    permissions:
       id-token: write
       contents: read
    steps:
      - uses: actions/checkout@v3
        with:
          submodules: true
          lfs: false
      - name: Install OIDC Client from Core Package
        run: npm install @actions/core@1.6.0 @actions/http-client
      - name: Get Id Token
        uses: actions/github-script@v6
        id: idtoken
        with:
           script: |
               const coredemo = require('@actions/core')
               return await coredemo.getIDToken()
           result-encoding: string
      - 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_GENTLE_WATER }}
          action: "upload"
          ###### Repository/Build Configurations - These values can be configured to match your app requirements. ######
          # For more information regarding Static Web App workflow configurations, please visit: https://aka.ms/swaworkflowconfig
          app_location: "/" # App source code path
          api_location: "" # Api source code path - optional
          output_location: "dist/angular-basic" # Built app content directory - optional
          production_branch: "dev"
          github_id_token: ${{ steps.idtoken.outputs.result }}
          ###### End of Repository/Build Configurations ######

  close_pull_request_job:
    if: github.event_name == 'pull_request' && github.event.action == 'closed'
    runs-on: ubuntu-latest
    name: Close Pull Request Job
    steps:
      - name: Close Pull Request
        id: closepullrequest
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN_GENTLE_WATER_030D91C1E }}
          action: "close"

In dieser Konfiguration:

  • Der main Zweig wird auf Commits überwacht.
  • Ein GitHub Actions-Workflow wird ausgelöst, wenn eine Pull-Anforderung auf dem main Zweig: geöffnet, synchronisiert, erneut geöffnet oder geschlossen wird.
  • Die build_and_deploy_job wird ausgeführt, wenn Sie Commits pushen oder eine Pull Anforderung gegen den in der on Eigenschaft aufgeführten Zweig öffnen.
  • Der app_location verweist auf den Ordner src, der die Quelldateien für die Webanwendung enthält. Verwenden Sie /, um diesen Wert auf den Repositorystamm festzulegen.
  • Der api_location verweist auf den Ordner api, der die Azure Functions-Anwendung für die API-Endpunkte der Website enthält. Verwenden Sie /, um diesen Wert auf den Repositorystamm festzulegen.
  • Der output_location verweist auf den Ordner public, der die endgültige Version der Quelldateien der App enthält. Er ist relativ zu app_location. Bei .NET-Projekten ist der Speicherort relativ zum Ausgabeordner für die Veröffentlichung.

Bitte ändern Sie die Werte für repo_token, action und azure_static_web_apps_api_token nicht, da sie von Azure Static Web Apps für Sie festgelegt werden.

Der Auftrag Pull Request schließen schließt automatisch den Pull Request, der den Build und die Bereitstellung ausgelöst hat. Dieser optionale Auftrag ist nicht erforderlich, damit der Prozess funktioniert.

Wenn ein Pull Request geöffnet wird, werden die GitHub Actions-Aktionen von Azure Static Web Apps erstellt, und die App wird in einer Stagingumgebung bereitgestellt. Danach überprüft der Auftrag Pull Request schließen, ob der Pull Request noch geöffnet ist, und schließt diesen mit einer Abschlussmeldung.

Dieser Auftrag trägt dazu bei, den Pull-Request-Workflow organisiert zu halten und veraltete Pull Requests zu verhindern. Da die Runtime den Pull Request automatisch schließt, bleibt Ihr Repository auf dem neuesten Stand, und Ihr Team wird über den Status benachrichtigt.

Der Auftrag Pull Request schließen ist Teil des GitHub Actions-Workflows von Azure Static Web Apps und schließt den Pull Request, nachdem er gemergt wurde. Die Azure/static-web-apps-deploy-Aktion stellt die App in Azure Static Web Apps bereit, wobei die azure_static_web_apps_api_token für die Authentifizierung erforderlich ist.

Benutzerdefinierte Buildbefehle

Für Node.js-Anwendungen können Sie genau steuern, welche Befehle während des Build-Prozesses der App oder API ausgeführt werden. Das folgende Beispiel zeigt, wie man Build mit Werten für app_build_command und api_build_command definiert.

Hinweis

Derzeit können Sie nur app_build_command und api_build_command für Node.js-Builds definieren. Verwenden Sie das Feld engines in der Datei package.json, um die Node.js Version anzugeben.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: '/'
  api_location: 'api'
  output_location: 'dist'
  app_build_command: 'npm run build-ui-prod'
  api_build_command: 'npm run build-api-prod'

...

inputs:
  app_location: 'src'
  api_location: 'api'
  app_build_command: 'npm run build-ui-prod'
  api_build_command: 'npm run build-api-prod'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)

Überspringen des Erstellens einer Front-End-App

Wenn Sie die volle Kontrolle über die Erstellung Ihrer Front-End-Anwendung benötigen, können Sie die automatische Erstellung umgehen und die in einem vorherigen Schritt erstellte Anwendung bereitstellen.

So überspringen Sie die Erstellung der Front-End-Anwendung:

  • Setzen Sie app_location auf den Speicherort der Dateien, die Sie bereitstellen möchten.
  • Setzen Sie skip_app_build auf true.
  • Setzen Sie output_location auf eine leere Zeichenkette ('').

Hinweis

Stellen Sie sicher, dass Sie Ihre staticwebapp.config.json-Datei auch in das output-Verzeichnis (Ausgabe) kopiert haben.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src/dist'
  api_location: 'api'
  output_location: ''
  skip_app_build: true

...

inputs:
  app_location: 'src/dist'
  api_location: 'api'
  output_location: '' # Leave this empty
  skip_app_build: true
  azure_static_web_apps_api_token: $(deployment_token)

Überspringen des Erstellens der API

Wenn Sie das Erstellen der API überspringen möchten, können Sie den automatischen Build umgehen und die in einem vorherigen Schritt integrierte API bereitstellen.

Schritte zum Überspringen des Erstellens der API:

  • Legen Sie in der Datei staticwebapp.config.json die Eigenschaft apiRuntime auf die richtige Runtime und Version fest. Die Liste der unterstützten Runtimes und Versionen finden Sie unter Konfigurieren von Azure Static Web Apps.

    {
  "platform": {
    "apiRuntime": "node:16"
  }
}

  • Setzen Sie skip_api_build auf true.

  • Legen Sie api_location auf den Ordner fest, der die erstellte API-App enthält, die bereitgestellt werden soll. Dieser Pfad ist relativ zum Repositorystamm in GitHub Actions und cwd in Azure Pipelines.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: "src" # App source code path relative to repository root
  api_location: "api" # Api source code path relative to repository root - optional
  output_location: "public" # Built app content directory, relative to app_location - optional
  skip_api_build: true

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  skip_api_build: true
  azure_static_web_apps_api_token: $(deployment_token)

Verlängern des Buildtimeouts

Standardmäßig sind die App- und API-Builds auf 15 Minuten beschränkt. Sie können das Buildtimeout verlängern, indem Sie die build_timeout_in_minutes-Eigenschaft festlegen.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  build_timeout_in_minutes: 30

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  build_timeout_in_minutes: 30
  azure_static_web_apps_api_token: $(deployment_token)

Ausführen von Workflows ohne Bereitstellungsgeheimnis

Unter Umständen muss Ihr Workflow die Verarbeitung auch dann fortsetzen können, wenn einige Geheimnisse fehlen. Legen Sie die Umgebungsvariable SKIP_DEPLOY_ON_MISSING_SECRETS auf true fest, um den Workflow so zu konfigurieren, dass er ohne definierte Geheimnisse fortgesetzt wird.

Wenn dieses Feature aktiviert ist, kann der Workflow fortgesetzt werden, ohne den Inhalt der Website bereitzustellen.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
env:
  SKIP_DEPLOY_ON_MISSING_SECRETS: true

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)
env:
  SKIP_DEPLOY_ON_MISSING_SECRETS: true

Umgebungsvariablen

Umgebungsvariablen für Ihren Build können über den Abschnitt env einer Auftragskonfiguration festgelegt werden.

Weitere Informationen zu den von Oryx verwendeten Umgebungsvariablen finden Sie unter Oryx-Konfiguration.

...

with:
  azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
  repo_token: ${{ secrets.GITHUB_TOKEN }}
  action: 'upload'
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
env: # Add environment variables here
  HUGO_VERSION: 0.58.0

...

inputs:
  app_location: 'src'
  api_location: 'api'
  output_location: 'public'
  azure_static_web_apps_api_token: $(deployment_token)
env: # Add environment variables here
  HUGO_VERSION: 0.58.0

Unterstützung für Monorepos

Ein Monorepo ist ein Repository, das Code für mehr als eine Anwendung enthält. Der Workflow verfolgt standardmäßig alle Dateien in einem Repository nach, aber Sie können die Konfiguration so anpassen, dass eine einzelne App als Ziel verwendet wird.

Geben Sie die Pfade in den Abschnitten push und pull_request an, um für eine Workflowdatei eine einzelne App als Ziel festzulegen.

Wenn Sie eine Monorepo einrichten, ist jede statische Anwendungskonfiguration nur auf Dateien für eine einzige Anwendung beschränkt. Die verschiedenen Workflowdateien befinden sich gemeinsam im Ordner .github/workflows des Repositorys.

├── .github
│   └── workflows
│       ├── azure-static-web-apps-purple-pond.yml
│       └── azure-static-web-apps-yellow-shoe.yml
│
├── app1  👉 controlled by: azure-static-web-apps-purple-pond.yml
├── app2  👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
├── api1  👉 controlled by: azure-static-web-apps-purple-pond.yml
├── api2  👉 controlled by: azure-static-web-apps-yellow-shoe.yml
│
└── README.md

Im folgenden Beispiel wird veranschaulicht, wie Sie einen paths-Knoten zu den Abschnitten push und pull_request einer Datei namens azure-static-web-apps-purple-pond.yml hinzufügen.

on:
  push:
    branches:
      - main
    paths:
      - app1/**
      - api1/**
      - .github/workflows/azure-static-web-apps-purple-pond.yml
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main
    paths:
      - app1/**
      - api1/**
      - .github/workflows/azure-static-web-apps-purple-pond.yml

In diesem Beispiel lösen nur Änderungen an den folgenden Dateien einen neuen Build aus:

  • alle Dateien im Ordner app1
  • alle Dateien im Ordner api1
  • Änderungen an der Workflowdatei azure-static-web-apps-purple-pond.yml der App

Um mehr als eine Anwendung in einem einzigen Repository zu unterstützen, erstellen Sie eine separate Workflow-Datei und verknüpfen Sie mit verschiedenen Azure Pipelines.

Nächste Schritte

Überprüfen von Pull Requests in Präproduktionsumgebungen